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Preface 


The Guide to Writing a Device Driver for VAX/VMS provides 
the information needed to write a device driver that runs 
under VAX/VMS Version 4.0 and to load that driver into the 
operating system. VAX/VMS makes no guarantee that drivers 
written for earlier versions of VAX/VMS will execute without 
modification on subsequent versions of the operating system. 
Although the intent is to maintain the existing interface, some 
unavoidable changes might occur as new features are added. 

The use of internal executive interfaces other than those 
described in this manual is discouraged. 


Intended Audience 

This manual is intended for system programmers who are 
already familiar with the VAX processor and the VAX/VMS 
operating system. The manual focuses on writing drivers 
for devices attached to the UNIBUS. Appendix G provides 
the additional information needed to write a driver for a 
device attached to the MASSBUS, and Appendix D provides 
information on writing a device driver for the Micro VAX I 
Q-bus. 


Structure of This Document 

This manual is organized into three parts. The first part 
introduces VAX/VMS device drivers and those aspects of 
the VAX processor and the VAX/VMS system that are essential 
to drivers. The following chapters make up Part I of this book. 

• Chapter 1 introduces the main concepts associated with 
drivers on VAX/VMS. 

• Chapter 2 describes an example of a line printer driver 
handling a data transfer. 

• Chapter 3 discusses synchronization mechanisms: interrupt 
priority levels, fork processes and fork queues, and resource 
wait queues. 
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• Chapter 4 discusses UNIBUS considerations for direct 
memory access (DMA) transfers. 

• Chapter 5 provides an overview of I/O processing and 
discusses the interaction between device drivers and 
VAX/VMS. 

Part II of this document describes how to code each part of the 

driver. The chapters in Part II are the following: 

• Chapter 6 contains a template for writing a device driver. 

• Chapter 7 details the macros that drivers invoke to create 
necessary tables. 

• Chapter 8 describes the writing of function-decision 
routines. 

• Chapter 9 describes the writing of a start I/O routine. 

• Chapter 10 describes the UNIBUS considerations for a start 
I/O routine. 

• Chapter 11 describes the writing of an interrupt-servicing 
routine. 

• Chapter 12 describes the writing of I/O completion and 
device timeout routines. 

• Chapter 13 describes the writing of unit and controller 
initialization routines, I/O cancellation routines, and error¬ 
logging routines. 

• Chapter 14 describes the loading of a driver into the system. 

• Chapter 15 describes the debugging tool XDELTA that you 
can use to debug a device driver. 

Part III contains the appendixes. 

• Appendix A describes the I/O database in detail. This is an 
important appendix for the programmer of a device driver. 

• Appendix B describes the VAX/VMS macros that drivers 
can invoke. 

• Appendix C describes the VAX/VMS routines that device 
drivers can call. 

• Appendix D describes the differences between UNIBUS 
drivers and Q-bus drivers, and describes how to write 
Micro VAX I Q-bus drivers. 
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• Appendix E contains a sample driver for a Q-bus device, in 
this case an RL01/RL02 disk. 

• Appendix F contains a sample driver for two connected 
DRlls. 

• Appendix G contains information needed to write a device 
driver for a device attached to the MASSBUS. 

• Appendix H lists the starting physical addresses for the 
UNIBUS memory address space associated with the VAX 
processors. 

• Appendix I describes each of the entry points a driver can 
have. 

• The glossary at the end of this manual defines I/O-related 
and driver-related terms. 


Associated Documents 

This document has the following prerequisites: 

• VAX Hardware Handbook 

• I/O-related portions of the VAX/VMS System Services 
Reference Manual 

• The appendix on naming conventions in the VAX/VMS 
Guide to Creating Modular Library Procedures 

• VAX/VMS I/O User's Reference Volume 

The following documents are associated with this manual: 

• VAX/VMS System Dump Analyzer Reference Manual 

• VAX/VMS System Management and Operations Guide 

• VAX/VMS Internals and Data Structures 
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Conventions Used in This Document 

This manual describes code transfer operations in three ways: 

1 The phrase "issues a system service call" implies the use of a 
CALL instruction. 

2 The phrase "calls a routine" implies the use of a JSB or BSB 
instruction. 

3 The phrase "transfers control to" implies the use of a BRB, 
BRW, or JMP instruction. 


Convention 

Meaning 

[ret] 

A symbol with a one-to six- 
character abbreviation indicates that 
you press a key on the terminal, for 
example, 1 ret 1 . 

[CTRL/xl 

The phrase CTRL/x indicates that 
you must press the key labeled 

CTRL while you simultaneously 
press another key, for example, 
CTRL/C, CTRL/Y, CTRL/O. 

$ SHOW TIME 

05-JUN-1985 11:55:22 

Command examples show all output 
lines or prompting characters that 
the system prints or displays in 
black letters. All user-entered 
commands are shown in red letters. 

$ TYPE MYFILE.DAT 

Vertical series of periods, or ellipsis, 
mean either that not all the data 
that the system would display in 
response to the particular command 
is shown or that not all the data a 
user would enter is shown. 

file-spec,... 

Horizontal ellipsis indicates that 
additional parameters, values, or 
information can be entered. 

[logical-name] 

Square brackets indicate that the 
enclosed item is optional. (Square 
brackets are not, however, optional 
in the syntax of a directory name in 
a file specification or in the syntax 
of a substring specification in an 
assignment statement.) 
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Summary of Technical Changes 


This manual applies to Version 4.0 of VAX/VMS. The following 
list summarizes the major technical changes from the Version 
3.0 manual: 

• For disk devices, the base of the device-dependent unit- 
control block must be defined using a new symbol, UCB$K_ 
LCL_DISK_LENGTH. This symbol replaces UCB$W_ 
BCR+2, which has been used to define the base of the 
device-dependent UCB for disks. 

• For tape devices, the base of the device-dependent UCB 
must be defined using a new symbol, UCB$K_LCL_TAPE- 
LENGTH. This symbol replaces UCB$L_DPC+4, which has 
been used to define the base of the device-dependent UCB 
for tapes. 

• For tape devices, the device-dependent field UCB$L_xx_ 
RECORD has been replaced with a device-independent field, 
UCB$L_RECORD. 

In the past, drivers had to define a field named UCB$U_xx_ 
RECORD, where xx was the device's mnemonic. This field 
contained the number of records between the beginning 
of the tape and the current position of the tape. This field 
had to be at a specific offset within the UCB (in Version 
3 this offset was 0A4 from the UCB base). In Version 4, 
UCB$L_RECORD serves this function. 

• All disk device drivers must support the I/O functions IO$_ 
PACKACK, IO$_AVAILABLE, and IO$_UNLOAD. The 
FDT routine EXE$LCLDSKVALID, supplied by VAX/VMS, 
must be the last FDT routine executed for all three functions. 

In addition, the driver's start-I/O routine must do the 
following: 

• Set the bit UCB$V_VALID in the field UCB$L_STS for 
the IO$_PACKACK function 

• Clear the bit UCB$V_VALID in the field UCB$L_STS 
for the IO$_AVAILABLE and IO$_UNLOAD functions 
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This represents the minimum support required for these 
functions. You can choose to have the functions provide 
other, additional services. For example, you might choose 
to have the IO$_UNLOAD function cause a drive to spin 
down. 

• The macro TIMEDWAIT has been added. 

• The value of IPL$_SYNCH has changed from 7 to 8, and 
IPL 7 has become a fork IPL. 

• The following fields must now be invoked explicitly in order 
to define symbols for your driver. Customer-written device 
drivers can no longer depend upon SYS.STB to resolve these 
symbols. 


Macro 

$DYNDEF 

$FCBDEF 

$IPLDEF 

$PCBDEF 

$PRVDEF 

SRSNDEF 

$VADEF 


Symbols Defined 

Codes defining types of dynamic data structures 
Offsets in the file-control block 
VAX/VMS interrupt-priority levels (IPLs) 

Offsets in the process-control block 
Bits that define process privileges 
Codes that define resource-wait states 
Virtual address structure 


• The EXEC routines ERL$RELEASEMB, EXE$FORKDSPTH, 
and IOC$ALTUBAMAP are no longer documented. 

• The EXEC routines EXE$ALOPHYCNTG, 
IOC$MOVFRUSER, IOC$MOVTOUSER, and 
EXE$LCLDSKVALID are now documented. 

• The DDTAB macro has a new, optional keyword, 
CLONEDUCB. Its default argument is IOC$RETURN. 

• The DDT has a new field, DDT$L_CLONEDUCB. 

• Appendix A describes the field IRPE$L_EXTEND. 

• The UCB has the new fields UCB$L_ORB, UCB$L_ 
LOCKID, and UCB$W_QLEN. 

• The UCB field UCB$W_STS has become UCB$L_STS. 
The symbol UCB$W_STS still exists, and it points to the 
low-order word of UCB$L_STS. 
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Summary of Technical Changes 


• The UCB no longer has fields UCB$L_VPROT or UCB$L_ 
OWNUIC. These fields have been placed in a new data 
structure, the object-rights block (ORB). See Appendix A for 
a description of this data structure. 

• Appendix D describes how to write a driver for Micro VAX I. 

• Appendix E contains an example of a driver for a MicroVAX 
I, RL02 disk. The other, subsequent appendices have been 
renumbered to reflect the insertion of this appendix. 

• Appendix I contains descriptions of all possible driver entry 
points. 
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Introduction to Device Drivers 


Under the VAX/VMS operating system, a device driver is a set 
of routines and tables that the system uses to process an I/O 
request for a particular device type. To understand how drivers 
are used by the VAX/VMS system, you must become familiar 
with the following basic concepts: 

• Machine dependence and machine independence 

• Asynchronous nature of a device driver 

• Fork processes 

• Process and interrupt contexts 

• Device dependence and device independence 

• I/O database 

• Synchronization mechanisms 

The beginning sections of this chapter describe the concepts 
listed above. The later sections describe the more concrete 
aspects of drivers, such as the functions they perform. 


1.1 Machine Dependence and Machine Independence 

The VAX/VMS operating system can run on any of the 
following VAX processors: the VAX-11/785, VAX-11/782, 
VAX-11/780, VAX-11/750, VAX-11/730, VAX-11/725, or 
MicroVAX I. Although these processors conform to the VAX 
architecture, there are some differences in design among the 
machines. To achieve machine-independence, follow the 
conventions outlined in this manual when you write a device 
driver. The driver will then operate on any processor without 
modification. 

To aid in driver debugging, sections of this manual discuss 
the internal differences between the various VAX processors. 
This section defines several terms that describe the hardware 
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configuration of each of these processors in a machine- 
independent manner: 

• Backplane interconnect—An internal processor bus that 
adapters use to communicate with main memory and the 
central processor. Chapter 4 describes the details for specific 
VAX processors. 

• UNIBUS adapter—An interface device between the 
backplane interconnect and a UNIBUS. UNIBUS adapters 
might be direct-vector or nondirect-vector devices. 

On a direct-vector UNIBUS adapter, UNIBUS device 
interrupts cause a processor interrupt that jumps to vectors 
in page two (or three) of the system-control block (SCB). 

On nondirect-vector UNIBUS adapters, UNIBUS device 
interrupts cause a UNIBUS adapter interrupt and are 
dispatched by the UNIBUS adapter interrupt-servicing 
routine. Chapters 3 and 4 discuss these adapters in more 
detail. 

• MASSBUS adapter—An interface device between the 
backplane interconnect and a MASSBUS. 

• Interrupt dispatcher—A combination of hardware and 
software that routes UNIBUS and MASSBUS device 
interrupts to the appropriate device driver's interrupt¬ 
servicing routine. The interrupt dispatcher's routing 
mechanism works differently depending upon whether 

the VAX processor in use accepts direct-vector or nondirect- 
vector UNIBUS interrupts and whether the adapter in use is 
a MASSBUS or UNIBUS adapter. 

• Physical address—The physical memory that UNIBUS 
and MASSBUS adapters address through the backplane 
interconnect. The different VAX processors have different 
amounts of physical address space. Physical addresses of 
device registers also vary with processor type. 

From the perspective of the hardware I/O architecture, the term 
VAX-11/730 refers to both the VAX-11/730 and the VAX-11 
/725. The term VAX-11/780 refers to the VAX-11/780, the 
VAX-11/782, and the VAX-11/785. 

On Micro VAX I systems, the Q22 bus serves the function 
that the backplane interconnect and the UNIBUS serve on 
other VAX systems. For the purpose of defining a generic 
terminology, the term UNIBUS can be construed as meaning 
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either the UNIBUS or, on a MicroVAX I, the Q22 bus. See 
Appendix D for details. 


1.2 Components of a Device Driver 

Normally, a device driver module consists of the following 

routines and tables: 

• An I/O preprocessing routine or routines that validate 
device-specific parameters of an I/O request, format data, 
allocate system buffers, and lock pages in memory 

• A start-I/O routine that activates the device 

• An interrupt-servicing routine that responds to interrupts 
from the device unit 

• An error-recovery routine that retries I/O operations and 
performs other error handling 

• An error-logging routine that writes the contents of device 
registers and other data into an error buffer for the system 

• A cancel-I/O routine that prevents further processing of an 
I/O request 

• An initialization routine that readies a device or controller 
for operation when the system is bootstrapped or during 
recovery from a power failure. 

• A driver-prologue table that describes the driver and the 
device type to the VAX/VMS procedure that loads drivers 
into the system 

• A driver-dispatch table that lists the entry point addresses of 
standard driver routines and records the size of diagnostic 
and error-logging buffers for the device type 

• A function-decision table that lists all valid function-codes 
for the device and lists the addresses of I/O preprocessing 
routines associated with each valid function 

With a few exceptions, which are noted in Chapter 7, the order 

of the various routines and tables within the driver module is 

not important. 
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1.3 Asynchronous Nature of a Device Driver 

Using the driver tables and other information maintained by the 
driver and the operating system, the system determines which 
routines to activate and when they should be activated. 

For example, when a user process calls the QIO system service, 
the system service calls various driver routines to perform 
preprocessing of the I/O request. Likewise, if a user process 
issues a Cancel I/O on Channel system service, the system 
service activates the driver's cancel-I/O routine. 

A device driver does not run from beginning to end. The 
system calls driver routines and suspends and reactivates them; 
the central processor interrupts and reactivates driver routines. 
Because little sequential processing of driver code occurs, 

VAX/VMS must assume the responsibility for synchronizing 
the execution of the various driver routines and synchronizing 
the execution of all drivers in the system. The VAX/VMS 
operating system synchronizes driver execution using fork 
processes, interrupt priority levels, fork queues, and resource- 
wait queues, described in the following sections. 


1.4 Fork Processes 

A fork process is a process that has minimal context. Fork 
processes can reference only the system's address space (SO). 
The VAX/VMS operating system creates and schedules a fork 
process by constructing a control block called a fork block, 
inserting the fork block in a fork queue, and requesting a 
software interrupt. Fork queues and fork process dispatching 
are described further in Section 1.8.3. 

A fork process has the following context: 

1 Three general registers 

2 Program counter (PC) 

3 A unit-control block in the I/O database that describes the 
target device of the I/O request 

The unit-control block also contains the driver's fork block. 
Section 1.8 describes the unit-control block and other data 
structures in the I/O database. 
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Like other processes, fork processes can be suspended and 
interrupted. VAX/VMS places a driver's fork process in a wait 
state when the process requests an unavailable resource, for 
example, a controller's data channel. The processor interrupts 
a fork process when the processor receives a request for an 
interrupt at a higher priority level. 

Fork processes execute at raised interrupt priority levels to 
minimize the number of interruptions. Fork processes can raise 
the priority level to 31 to block all other interrupts, if necessary. 


The system automatically saves registers for interrupted fork 
processes and restores these registers when the process is 
reactivated. The operating system does not swap fork processes 
because the fork block and all data about the fork process reside 
in nonpaged system memory. 


1.5 Process Context and Interrupt Context 

Because a device driver consists of a number of routines that 

are activated by VAX/VMS, the operating system for the most 

part determines the context in which the routines execute. 

As an example, consider the following write request that occurs 

without error: 

• A user process executing in user mode calls the QIO system 
service to write data to a device. 

• The QIO system service gains control in user-process context 
but in kernel mode. 

• The system service uses the driver's function-decision 
table to call the appropriate preprocessing routines. These 
routines, called FDT routines, execute in full process context 
in kernel mode. 

• When preprocessing is complete, a VAX/VMS routine 
creates a fork process to execute the driver's start-I/O 
routine in kernel mode. 

• The start-I/O routine activates the device unit and suspends 
itself. At this point, VAX/VMS suspends the fork process 
executing the start-I/O routine and saves sufficient context 
to reactivate the start-I/O routine at the point of suspension. 
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• When the device completes the data transfer, it issues an 
interrupt. The interrupt causes the system to activate the 
driver's interrupt-servicing routine. 

• The interrupt-servicing routine executes to handle the device 
interrupt. It then causes the start-I/O routine to resume in 
interrupt context. 

• The start-I/O routine regains control in interrupt context but 
almost immediately issues a request to the operating system 
to transform its context to that of a fork process. This action 
dismisses the interrupt. 

• When reactivated in fork process context, the start-I/O 
routine performs device-specific I/O completion and passes 
control to the system for additional I/O postprocessing. 

• VAX/VMS I/O postprocessing performs processing at a 
software interrupt priority level and then issues a kernel¬ 
mode asynchronous system trap (AST) for the user process 
requesting I/O. 

• When the kernel-mode AST is delivered, the AST routine 
executes in full process context at kernel mode to deliver 
data and status to the process. If the original request 
specified a user-mode AST, the kernel-mode AST queues it. 

• When the user process gains control, the user's AST routine 
executes in full process context in user mode. 

The majority of driver routines execute in fork process context. 

It is essential, however, that the various driver routines not 

attempt to exceed the limitations of the context in which they 

execute. 


1.6 Device Dependence and Device Independence 

The VAX/VMS approach to I/O is that the operating system 
should perform as much of the processing of an I/O request 
as possible and that drivers should restrict themselves to the 
device-specific aspects of I/O processing. To accomplish this, 
the VAX/VMS operating system provides drivers with the 
following services: 

• The QIO system service preprocesses an I/O request by 
performing those functions and checks that are common 
to all devices; for example, it validates the arguments in 
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the I/O request that are not device specific. This type of 
preprocessing is called device-independent preprocessing. 

• The VAX/VMS operating system includes a number of 
routines that drivers can call to perform I/O preprocessing, 
allocate and deallocate resources, and synchronize driver 
execution. 

• VAX/VMS I/O postprocessing performs the device¬ 
independent I/O postprocessing for all I/O requests. 

Thus, drivers can leave the device-independent I/O processing 
to the operating system and concentrate on the device¬ 
dependent aspects of a device unit, those aspects that vary 
from device type to device type. In addition, drivers can call 
the VAX/VMS system to perform many functions that are 
device specific but common to several devices. 


1.7 The I/O Database 

Because a driver and the operating system cooperate to process 
an I/O request, they must have a common I/O database. 
Under VAX/VMS, the I/O database consists of three main 
parts: 

• Driver tables that allow the system to load drivers, validate 
device functions, and call drivers at their entry points 

• Control blocks that describe every bus adapter, every device 
type, every device unit, every controller, and every logical 
path (channel) from a process to a device 

• I/O-request packets that define individual requests for I/O 
activity 

The three driver tables are defined in every driver. Section 1.2 
lists these tables. Appendix A describes each of the control 
blocks and the I/O-request packet in detail. 

Figure 1-1 illustrates some of the relationships among 
VAX/VMS I/O routines, the I/O database, and a device driver. 
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Figure 1-1 The I/O database 
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1.7.1 


Control Blocks in the I/O database 

Control blocks in the I/O database describe peripheral 
hardware, and are used by VAX/VMS to synchronize access 
to devices. VAX/VMS creates these control blocks either at 
system start-up or when a user-written driver is loaded into the 
system. 

Drivers refer to some or all of the following control blocks: 

• Device-data block (DDB) 

• Unit-control block (UCB) 

• Channel-request block (CRB) 
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• Interrupt-dispatch block (IDB) 

• Adapter-control block (ADP) 

• Channel-control block (CCB) 


1.7.1.1 Device-Data Block 

A device-data block contains information common to all devices 
of the same type that are connected to a particular controller. 

It records the generic device name concatenated with the 
controller designator, and the name and location of the driver 
for those devices. In addition, the device-data block contains 
a pointer to the first unit-control block for the device units 
attached to the controller. 


1.7.1.2 Unit-Control Block 

The system defines a unit-control block for each device attached 
to the system. A unit-control block defines the characteristics 
and current state of an individual device unit. In addition, it 
contains the fork block used by the unit's device driver and the 
listhead for the queue of pending I/O-request packets for the 
unit. 

Because drivers execute as fork processes that are created for 
each I/O operation on a unit, the unit-control blocks are the 
focal point of the I/O database. When a driver is suspended or 
interrupted, the UCB fork block holds the driver's context. 


1.7.1.3 Channel-Request Block 

The operating system creates a channel-request block for each 
controller. A channel-request block defines the current state of 
the controller and lists the devices waiting for the controller's 
data channel. In addition, it contains the code that dispatches a 
device interrupt to the interrupt-servicing routine for that unit's 
driver. 


1.7.1.4 Interrupt-Dispatch Block 

The system creates an interrupt-dispatch block for each 
controller. An interrupt-dispatch block lists the device units 
associated with a controller and points to the unit-control block 
of the device unit that the controller is currently servicing. In 
addition, an interrupt-dispatch block points to device registers 
and the controller's UNIBUS adapter. 
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1.7.1.5 Adapter-Control Block 


An adapter-control block defines the characteristics and current 
state of a UNIBUS or MASSBUS adapter. An adapter-control 
block for the UNIBUS adapter contains the queues and 
allocation bit maps necessary to allocate adapter resources. 
VAX/VMS provides routines that drivers can call to interface 
with their UNIBUS adapter. 


1.7.1.6 


Channel-Control Block 


A channel is a logical path between a process and the unit- 
control block of a specific device unit. The channel-control 
block describes this path. Each process owns a number of 
channel-control blocks. When a process issues the Assign I/O 
Channel system service, the system writes a description of the 
assigned device to the channel-control block. 

Unlike the data structures mentioned earlier, a channel-control 
block is not located in nonpaged system space, but in the 
process's control region (PI space). 



I/O-Request packets 


1.7.2 


The third part of the I/O database is a list of I/O-request 
packets (IRPs). When a process requests I/O activity, the 
operating system constructs a packet of data, called an I/O- 
request packet, that describes the I/O request in standard 
form. 

The I/O-request packet contains fields into which the system 
and driver I/O preprocessing routines can write information, 
such as device-dependent parameters specified in the call to the 
QIO system service. Later, the system sends the I/O-request 
packet to the device driver start-I/O routine. The driver's start- 
I/O routine uses the packet as its source of detailed instructions 
about the operation to be performed. The packet includes 
buffer addresses, a pointer to the target device, I/O-function 
codes, and pointers to the I/O database. 
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1.8 Synchronization 

The VAX/VMS operating system uses hardware and software 
interrupt priority levels (IPLs) with their associated interrupts, 
fork queues, and resource-wait queues to synchronize the 
execution of all drivers within the system and to synchronize 
execution of various routines within a driver. 


1.8.1 Interrupt Priority Levels 

The VAX processor defines 32 interrupt priority levels (0 
through 31). The higher numbered IPLs are reserved for 
hardware interrupts, for example, device interrupts. The 
operating system uses the lower numbered IPLs. A higher IPL 
always takes precedence over a lower IPL. The VAX Hardware 
Handbook describes the VAX processors' use of IPLs. 

The following IPLs are of particular interest to drivers: 

• Hardware device IPLs (20 through 23); driver interrupt¬ 
servicing routines execute at these IPLs. 

• Fork-processing IPLs (8 through 11); a driver's fork 
processes execute at one of these IPLs. 

• All access to system-wide data structures, including the I/O 
database, must occur at IPL$_SYNCH, IPL 8. 

• I/O completion IPL (IPL 4); VAX/VMS gains control to 
begin its device-independent I/O postprocessing at this IPL. 

• AST delivery IPL (IPL 2); VAX/VMS uses this IPL to 
coordinate the delivery of an AST to a user process. The 
QIO system service also executes at this IPL. 
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1 . 8.2 


1.8.3 


Device Interrupts 

When the processor grants a device interrupt, the processor and 
the VAX/VMS interrupt dispatcher save the current process 
context. The processor pushes the PC and PSL at the time of 
the interrupt onto the interrupt stack. In addition, the interrupt 
dispatcher saves RO through R5 on the stack. 

The interrupt-servicing routine activated as a result of the 
interrupt follows conventions to preserve all other context of 
the interrupted process, as follows: 

• Uses only RO through R5 

• Cleans up the stack after use 

When the interrupt has been serviced, the driver's interrupt¬ 
servicing routine restores RO through R5 from the stack. The 
processor restores the previous PC and PSL of the interrupted 
code. The interrupted process then resumes execution without 
any awareness of the interruption. 


Fork Queues 

When an interrupt-servicing routine completes the handling of 
a device interrupt, it transfers control to the driver to complete 
device-dependent processing of the I/O request. When the 
driver regains control, it is executing at device IPL. Almost 
immediately, the driver should lower IPL to the driver's fork 
IPL so that it does not block other device interrupts. A driver 
lowers IPL by invoking a VAX/VMS macro that creates a fork 
process to execute at the driver's fork IPL. 

Each fork IPL has an associated fork queue. A VAX/VMS 
macro queues the driver's fork block to the fork queue that 
corresponds to the driver's fork IPL, and issues a software 
interrupt request for that IPL. When the software interrupt is 
granted, the VAX/VMS fork dispatcher dequeues fork blocks 
from the fork queue corresponding to IPL at which the interrupt 
was granted and reactivates the driver at the point following 
the macro invocation. 
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1.8.4 


Resource-Wait Queues 

Drivers compete for the following shared resources: 

• The central processor 

• The UNIBUS adapter's mapping registers, if the device is a 
DMA device 

• The UNIBUS adapter's buffered data paths, if the device is a 
DMA device 

• The controller's data channel, if the device is attached to a 
multiunit controller 

When a driver's fork process needs an unavailable resource, 
VAX/VMS resource management routines perform the 
following steps: 

1 Save fork process context in the device's UCB fork block 

2 Insert the address of the UCB fork block in a resource-wait 
queue 

3 Suspend the driver's fork process 

When another driver's fork process frees the necessary 
resource, the VAX/VMS resource management routines take 
the following steps to reactivate the next driver's fork process: 

1 Remove the next UCB fork block from the resource-wait 
queue 

2 Restore fork process context into the registers 

3 Reactivate the suspended driver's fork process 

The VAX/VMS resource management routines allow the 
driver's fork process to be unaware of its suspension and 
reactivation. 
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1.9 Functions of a Device Driver 

A VAX/VMS device driver controls I/O operations on a 

peripheral device by performing the following functions: 

• Defines the peripheral device for the rest of VAX/VMS 

• Defines the driver for the system procedure that loads the 
driver into system virtual address space and that creates the 
driver's associated data structures 

• Readies the device and/or its controller for operation at 
system start-up and during recovery from a power failure 

• Performs device-dependent I/O preprocessing 

• Translates programmed requests for I/O operations into 
device-specific commands 

• Activates the device 

• Responds to hardware interrupts generated by the device 

• Responds to device timeout conditions 

• Responds to requests to cancel I/O on the device 

• Reports device errors to an error-logging program 

• Returns status from the device to the process that requested 
the I/O operation 

The driver-prologue table, described in Section 7.1, performs 

the first two functions listed above. Driver routines perform the 

remaining functions. 


1.9.1 Initialization Routines 

Most device controllers and device units require initialization 
when the VAX/VMS driver-loading procedure loads the driver 
into memory and when the VAX/VMS system recovers from a 
power failure. The amount and type of initialization varies from 
device type to device type. Section 13.1 provides additional 
information about device driver initialization routines. 
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1.9.2 FDT Routines 

Every driver contains a function-decision table (FDT) that 
indicates the I/O preprocessing routines that are to be executed 
for various functions on the device. When a user process 
calls the QIO system service, the system service uses the I/O- 
function code specified in the request to select one or more FDT 
routines for execution. FDT routines perform such functions 
as allocating buffers, locking pages in memory, and validating 
device-dependent parameters (PI through P6) of the I/O 
request. 

The driver contains FDT routines that are device-dependent. 
VAX/VMS provides additional FDT routines that perform 
processing common to many I/O functions, as described in 
Section 8.7. It is advisable for drivers to use FDT routines 
supplied by the operating system whenever possible. 

Because FDT routines are called by the QIO system service, 
they execute in full user process context. As a result, FDT 
routines have access to user-specified buffers located in the 
process address space; these buffers are not available to driver 
routines executing in fork context. 


1.9.3 Start-I/O Routine 

The start-I/O routine executes in a driver's fork process to 

perform the following device-dependent functions: 

• Translate the I/O-function code into a device-specific 
command 

• Transfer the details of the request from the I/O-request 
packet to the device's unit-control block 

• Obtain access to the controller if it is a multiunit controller 

• Obtain the necessary UNIBUS resources if the transfer is a 
direct memory access (DMA) transfer 

• Modify the device registers to activate the device 

• Perform device-dependent I/O postprocessing after the 
transfer occurs 
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The start-I/O routine might be forced to wait for the controller 
or UNIBUS resources to become available. In either case, 
VAX/VMS suspends the routine and reactivates it when the 
resources are free. Section 1.8.4 describes the context that 
VAX/VMS saves for the suspended routine. 

After activating the device, the start-I/O routine invokes the 
VAX/VMS wait-for-interrupt macro. The wait-for-interrupt 
macro suspends the driver. The driver remains suspended until 
the driver's interrupt-servicing routine handles the interrupt and 
returns control to the driver. At that point, the driver performs 
device-dependent I/O postprocessing and then transfers control 
to VAX/VMS for device-independent I/O postprocessing. 


1.9.4 Interrupt-Servicing Routine 

When a device interrupt occurs, VAX/VMS transfers control 
to the device driver's interrupt-servicing routine in interrupt 
context. The interrupt-servicing routine determines whether the 
interrupt was expected or not and takes the appropriate action. 
Then the interrupt-servicing routine reactivates the driver for 
I/O postprocessing. 


1.9.5 Device-Timeout Handler 

As the result of an error condition or a device's being off line, 
it is possible for a device to fail to complete a transfer in a 
reasonable period of time. This condition is called device 
timeout. When a start-I/O routine invokes the wait-for- 
interrupt macro, it specifies the interval in which the device 
can complete a transfer without timing out and the name of a 
timeout handler that the system is to invoke if a timeout occurs. 
This information is recorded in the device's unit-control block. 

Once every second, the VAX/VMS system timer checks all 
devices in the system for device timeout. When it locates a 
device that has timed out, it calls the timeout handler. 
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1.9.6 Cancel-I/O Routine 

VAX/VMS provides the Cancel I/O on Channel system service 
that user processes can call to cancel I/O requests. The Cancel 
I/O on Channel system service, in turn, calls the driver's 
cancel-I/O routine. VAX/VMS also calls the driver's cancel- 
I/O routine when the device's reference count goes to zero, 
which occurs when all users that assigned channels to the 
device have deassigned them. 


1.9.7 Error-Logging Routine 

The driver's error-logging routine fills an error-log buffer with 
information about the error, for example, the register contents 
at the time of the error. VAX/VMS provides a routine that 
drivers can call to allocate an error log buffer and transfer 
control to the register dump routine. 


1.10 An Example of a UNIBUS I/O Request 

Figure 1-2 illustrates how the VAX/VMS operating system and 
the device driver process a user process request for a read I/O 
operation on a DMA UNIBUS device. 

Figure 1-2 Processing a Sample I/O Operation 



ZK-909-82 


1-17 





























Introduction to Device Drivers 


The processing of the sample I/O request illustrated in Figure 
1-2 occurs in the following steps: 

1 A process requests I/O operation. A user process requests 
data from the device by issuing either of the following: 

• An RMS get-record function call (which results in a call 
to the QIO system service) 

• A QIO system service call 

The user process specifies the target device, a read function 
code, and the address of a buffer in which the data is to be 
read. 

2 The operating system performs I/O preprocessing. The 

QIO system service validates the request and locates control 
blocks in the I/O database that describe the device and 
its driver. The system service also allocates and initializes 
an I/O-request packet to contain a description of the I/O 
request. The system service then calls a reading routine in 
the driver. 

3 The driver performs I/O preprocessing. The driver 
function-decision table routine verifies that the user buffer 
resides in virtual memory pages that can be modified by the 
requesting process, locks the buffer pages in memory, and 
adds details of the I/O operation to the I/O-request packet. 
The read FDT routine then calls the operating system to 
send the I/O-request packet to the driver. 

4 VAX/VMS creates a driver's fork process. A VAX/VMS 
routine creates a fork process in which the device driver can 
execute. The routine activates the driver's fork process by 
transferring control to the driver's start-I/O routine. 

5 The driver readies the UNIBUS adapter. For DMA 

transfers, the driver's fork process calls VAX/VMS routines 
that control the UNIBUS adapter hardware to map UNIBUS 
addresses into physical addresses for the transfer. 

6 The driver activates the device. The fork process activates 
the device by setting bits in device registers. 

7 The driver waits for an interrupt. A VAX/VMS 
routine saves the context of the driver's fork process and 
relinquishes the processor until an interrupt occurs. 
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8 The device requests an interrupt. When the data transfer 
is complete, the device requests a hardware interrupt that 
causes the system to dispatch to the driver's interrupt¬ 
servicing routine. 

9 The driver services the interrupt. The driver's interrupt¬ 
servicing routine handles the interrupt and reactivates 
the driver, which reads device registers to obtain status 
information about the transfer. 

10 The operating system inserts the driver in a fork queue. 

The driver requests that the process be reactivated at a lower 
software interrupt priority level. 

11 The fork dispatcher reactivates the driver's fork process. 

When processor priority permits, the VAX/VMS fork 
dispatcher reactivates the driver as a fork process. 

12 The driver completes the I/O operation. The driver's fork 
process completes device-dependent processing of the I/O 
request and returns the I/O status to VAX/VMS. 

13 VAX/VMS completes the I/O operation. The VAX/VMS 
I/O postprocessing routines copy the I/O status into process 
address space and/or general registers and return control to 
the user process. 

Only four of these 13 steps describe the driver's I/O 
preprocessing and fork processing. The VAX/VMS I/O- 
support routines perform I/O processing common to many 
I/O requests. Driver writing is further simplified by the use of 
VAX/VMS routines that handle device-independent functions. 

The example above condenses and simplifies the processing of 
an I/O operation by ignoring such issues as: 

• The association of a device with a process, which is to say 
device assignment 

• Simultaneous I/O requests for one device 

• The hardware's interrupt priority levels 

• Driver competition for shared system and UNIBUS-adapter 
resources 

• Driver competition for a multiunit controller 
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• Driver recovery from device errors or power failure 

Later chapters discuss each of these issues in relation to device 
drivers. 


1.11 The UNIBUS 

On VAX/VMS systems other than the MicroVAX I, the 
backplane interconnect connects the central processor to 
memory. The backplane interconnect also connects the 
UNIBUS adapter and MASSBUS adapter to memory and to 
the central processor. Peripheral devices attach to either the 
UNIBUS, for UNIBUS devices, or the MASSBUS, for MASSBUS 
devices, as illustrated in Figure 1-3. 

The VAX Hardware Handbook describes the hardware 
components diagrammed in Figure 1-3. 

Nonstandard devices, which is to say customer-supplied 
devices, normally are connected to the UNIBUS, but can also be 
attached to the MASSBUS or to the DR32 device interconnect. 
DIGITAL supplies a device driver and an application library for 
the DR32 device; see the chapter on the DR32 Interface Driver 
in the VAX/VMS I/O User's Guide for further information. 

To activate a direct-memory-access (DMA) transfer on the 
UNIBUS, a driver must first obtain mapping registers, and, 
optionally, a buffered data path. The driver calls VAX/VMS 
routines that interface with the UNIBUS adapter to allocate 
these resources on behalf of the driver. 

The direct data path maps each UNIBUS transfer to a 
backplane-interconnect transfer. For each UNIBUS transfer, 
there is one backplane-interconnect transfer. Each backplane- 
interconnect operation transfers a single word or byte of data 
depending on the device. A buffered data path, on the other 
hand, allows multiple UNIBUS transfers to be assembled and 
transferred in one backplane-interconnect operation. 

Drivers performing transfers other than DMA transfers are 
generally not concerned with UNIBUS adapter operation. 
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Instead of creating a complete device driver for a device that 
does not perform DMA transfers, you can connect the process 
to the device interrupt vector to program the device from a 
user process. For a description of how and when to connect 
a process to an interrupt vector, consult the Version 4 Release 
Notes. 


Figure 1-3 VAX Hardware Configuration 
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1.12 Programmed I/O and Direct-Memory-Access I/O 

Devices transfer data using programmed I/O (PIO) transfers or 
direct-memory-access (DMA) transfers. 

Devices that perform programmed I/O transfer data as single 
words or bytes using device registers. After each transfer is 
completed, the device notifies the central processor. 

Devices that perform DMA transfers do not require the 
central processor so frequently. Once the driver activates the 
device, the device can transfer a large amount of data without 
requesting an interrupt after each of the smaller amounts. 
Normally, the driver of a DMA device allocates a UNIBUS 
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buffered data path and UNIBUS mapping registers for I/O 
transfers. 


1.13 Buffered I/O and Direct I/O 

Drivers can perform I/O transfers using either of the following 
methods: 

• Buffered I/O 

• Direct I/O 

Buffered I/O allows data to be buffered in system address 
space. When the transfer is complete, the data is transferred to 
the user process's buffer. The driver can refer to the buffer in 
system space using system virtual addresses. Often, a driver 
uses buffered I/O for devices that perform programmed I/O, 
for example, line printers and card readers. 

Direct I/O allows data to be placed directly in the user process's 
buffer. The driver must lock the pages containing the buffer in 
physical memory and refer to them using page-frame numbers 
(PFNs). Normally, a driver uses direct I/O and a buffered data 
path for devices that perform DMA transfers. 

The trade-off between buffered I/O and direct I/O is the time 
required to move the data into the user's buffer versus the 
time required to lock the buffer pages in memory. Chapter 8 
provides additional information. 


1.14 Loadable Drivers 

The VAX/VMS operating system provides a procedure that 
allows a suitably privileged user to load drivers into a running 
VAX/VMS system. The System Generation Utility (SYSGEN) 
described in full in the VAX/VMS Utilities Reference Manual, 
supports commands that invoke the driver-loading procedure: 

• The LOAD command loads a driver into the system. 

• The CONNECT command creates the I/O database for 
additional devices of the same type. 

• The RELOAD command loads a previously loaded driver. 
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The driver-loading procedure uses information provided in 
the LOAD command and information contained in driver 
tables to load the driver into virtual memory and create the 
associated database. The driver-prologue table, which must 
be the first executable code in the driver module, contains the 
information that the loading procedure needs. Specifically, the 
driver-prologue table contains the following: 

• Address of the end of the driver; the loading procedure uses 
this to determine the size of the driver 

• Driver loader flags that indicate whether the device needs 
a system-page-table entry and whether the driver can be 
reloaded 

• Size of the unit-control block 

• Address of a routine to call if the driver is reloaded 

• Name of the device driver module 

The driver-prologue table is followed by two lists of fields that 
require initialization. 

• I/O database fields to be initialized the first time the driver 
is loaded 

• Fields to be initialized every time the driver is reloaded, 
regardless of whether a bootstrap of the system has occurred 
since the last reload of the driver. 

With the information provided in the driver-prologue table 
and the two lists of fields, the driver-loading procedure can 
both load and reload drivers and perform the I/O-database 
initialization that is appropriate to either situation. 
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Discussion of a Queue-1 /O 
Request 


This chapter describes what takes place during the processing 
of a queue-I/O request. For simplicity, the device chosen is the 
LP11 printer. 

The LP11 is a buffered printer. A user process can request the 
following functions on this printer: 

• Write data to the printer 

• Read the printer's device characteristics 

• Alter the printer's device characteristics 

This chapter describes two aspects of printer I/O processing: 

• The portions of the VAX/VMS device driver for an LP11 
printer that are used in servicing a write request 

• The VAX/VMS components with which the driver interacts 
to process the write request 

The LP11 was selected for this discussion because it is a simple 
driver but still illustrates many driver principles. Although the 
LP11 is usually spooled, for purposes of this discussion, assume 
that it is not. 

The first-time reader of this document might not understand all 
of the points made in this chapter; however, the chapter should 
provide some insight into driver flow and I/O processing. 

Figure 2-1 illustrates the flow of execution through VAX/VMS 
routines and the printer driver to satisfy this I/O request. 

The double-sided boxes in Figure 2-1 indicate processing 
performed by driver subroutines. Boxes shown above the 
dotted line indicate processing in the context of the user 
process. Boxes below the dotted line indicate processing in 
fork or interrupt context. 
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2.1 Driver Code for the LP11 Write Function 

The VAX/VMS device driver for an LP11 printer implements a 

write function using the following parts of the driver: 

• An FDT routine that reformats the user-supplied data 

• A start-I/O routine that writes data to the device print buffer 
until the printer enters a busy state to print the contents of 
the buffer 

• Code that modifies a device register to enable interrupts 
from the printer 

• An interrupt-servicing routine that returns control to the 
driver's fork process after a hardware interrupt from the 
printer 

• Code that returns I/O status to a VAX/VMS I/O completion 
routine 


Figure 2—1 A Printer Write Function 
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2.2 A User Process's I/O Request 


A user process writes a line to the printer by calling the Queue- 
I/O-Request system service, specifying the write-virtual-block 
function-code as follows: 

$QIO_S CHAN = CHANNEL_NUMBER,- 
FUNC = #IO$_WRITEVBLK,- 
EFN = #6,- 

IOSB = STATUS.BLOCK,- 
PI = BUFFER.ADDRESS,- 
P2 = #BUFFER_SIZE,- 
P4 = #~X30 

The parameters PI, P2, and P4 are device-dependent 
parameters. 


2.3 I/O Preprocessing by VAX/VMS 

When called, the Queue-I/O-Request system service first 

validates that the I/O request is correctly specified. The I/O 

request must meet the following criteria: 

• The location CHANNEL-NUMBER must contain a channel 
number that serves as an index into the process I/O channel 
list. The process must have previously assigned the printer 
device to this process channel using the Assign I/O Channel 
system service. 

During verification of the channel number, the Queue-I/O- 
Request system service obtains the address of the printer 
driver's function-decision table (FDT). Figure 2-2 illustrates 
the chain of pointers from the channel index number to 
the FDT address. The arrow, for example, from the CCB 
to the UCB represents the pointer that the CCB contains, a 
longword that in turn contains the address of the UCB. 

As a result of chaining through the I/O database, the 
Queue-I/O-Request system service determines what device 
is the target of the request. 

• The printer FDT must list IO$_WRITEVBLK as a valid 
function for the device. 

• The event flag number must be valid. 

• The process buffered I/O request quota must permit the 
Queue-I/O-Request system service to perform a buffered- 
I/O request without exceeding the process's quotas. 
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• The process must have write access to the user-specified 
location to be used as an I/O-status block. 


If all of the checks described above succeed, the Queue- 
I/O-Request system service creates an I/O-request packet 
in nonpaged system address space. The service then writes 
all known details about the I/O request into the I/O-request 
packet. 

If the target device for the I/O request is not file-structured, 
the Queue-I/O-Request system service changes any virtual- 
function code to its equivalent logical-function code when it 
builds the I/O-request packet. Thus, for a printer device, IO$_ 
WRITEVBLK is translated to IO$_WRITELBLK. 


Figure 2-2 Locating a Function-Decision Table 
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2.4 I/O Preprocessing by the Driver 

Once it has validated the I/O request, the Queue-I/O-Request 
system service scans the function-decision table for an entry 
that associates the IO$_WRITELBLK function-code with an 
FDT routine. The system service calls the routine, which in the 
case of the printer driver is a device-specific routine located in 
the printer device driver. 

The FDT routine confirms that the requesting process has read 

access to the buffer starting at BUFFER_ADDRESS. Then, the 

FDT routine buffers data from the process address space into 
system address space in the following steps: 

• It calculates the length of the required system space buffer. 

• If the process byte count quota for buffered I/O (BYTCNT) 
permits, the routine allocates a buffer from system address 
space, stores the address of the buffer in the I/O-request 
packet, and decreases the current process byte count quota. 

• It then synchronizes with other possible subprocesses 1 to 
read and write fields of the printer's unit-control block. 

• It reads the description of the printer's current line and page 
position from the device's unit-control block. 

• It reformats the data from the process buffer into the system 
buffer, adding carriage control characters, as specified in the 
I/O request argument P4, before and after the data. 

Formatting includes such functions as the replacement of 
horizontal tabs with multiple spaces and the replacement of 
lowercase characters with uppercase characters, if necessary. 

• It rewrites updated line and page positions into the device's 
UCB. This information indicates what the current location on 
the page being printed will be where the request completes. 

• Finally, the routine transfers control to a VAX/VMS routine 
that queues the I/O-request packet to the device driver. 


1 For example, if a process allocates a printer, it is possible for the process and any of its subprocesses to 
issue write requests to the printer concurrently. 
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All of the I/O processing described to this point occurs in 
the context of the user's process. The user address space is 
mapped, and the processor's interrupt priority level (IPL) is 
still low enough to permit process scheduling and paging. 
Subsequent queuing of the transfer request to the driver and 
all resulting driver processing occur at higher interrupt priority 
levels that synchronize the driver's handling of the device, as 
described in Chapter 3. 


2.5 Queuing the l/O-Request Packet to the Driver 

Before queuing the I/O-request packet to the proper driver, 
the VAX/VMS queuing routine raises the interrupt priority 
level to the driver's fork level stored in the unit-control block 
(in UCB$B_FIPL). Raising IPL to fork level synchronizes the 
driver's access to the unit-control block. 

If the device is idle, which is to say that if the busy bit 
(UCB$V_BSY) in the I/O status word of the unit-control 
block is clear, VAX/VMS can transfer control to the driver. The 
driver-dispatch table contains the entry point to the driver's 
start-I/O routine. To find the proper entry point, the queuing 
routine chains through the I/O database to the driver-dispatch 
table, as follows: 

UCB —> DDT —> Entry point to start-I/O routine 

If the device unit is busy with another transfer, VAX/VMS 
inserts the I/O-request packet in a queue of packets waiting for 
the unit. The unit-control block contains the head of the queue. 
The packet's position in the queue depends on the scheduling 
priority of the process issuing the request. 


2.6 Driver Device Activation 

The LP11 printer controller accepts data into a data buffer until 
the print buffer is full or the driver writes a carriage-control 
character into the print buffer. When either event occurs, the 
printer sets a busy bit in the device's control/status register. 
Then a device driver sets the interrupt-enable bit in the device's 
control/status register and waits for the printer to interrupt. 
When the printer requests a hardware interrupt, the driver can 
resume putting characters in the print buffer. 
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The driver routine writes to the printer data buffer according to 
the following sequence: 

1 The driver locates the LP11 device registers using a chain of 
pointers starting at the device's unit-control block (UCB). 

UCB --> CRB -> IDB --> CSR address 

The CSR address is always the address of the printer control 
/status register, and all other device registers are at fixed 
offsets from this address. In contrast to many other devices, 
such as disks, the LP11 printer does not share a controller 
with other devices; therefore, no arbitration for ownership 
of the controller is required. 

2 The driver examines the device's control/status register to 
see if the device is ready to accept characters. 

3 If the device is ready, the driver writes a byte of data into 
the printer data buffer and decreases the count of bytes to 
transfer. It then repeats step 2. 

4 If the device is not ready, which is to say that if the device's 
internal buffer is full, the driver raises IPL to 31 to block all 
interrupts and sets the interrupt-enable bit in the device's 
control/status register. 

After enabling interrupts, the driver invokes a VAX/VMS 
wait for interrupt macro to suspend driver processing until 
the printer requests an interrupt or the device times out. 


2.7 Waiting for a Device Interrupt 

The VAX/VMS wait-for-interrupt routine suspends the driver 

by performing the following functions: 

• Saving driver context (R3, R4, and the address of the next 
instruction in the driver) in the device's unit-control block 

• Calculating the time at which the device will time out 

• Setting bits in the device's unit-control block to indicate that 
the driver expects a device interrupt within a specified time 
period 

VAX/VMS then drops IPL back to fork level and returns control 

to the caller of the driver's start-I/O routine. 
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The driver remains in a suspended state until one of two events 
occurs: 

• The printer requests a hardware interrupt. 

• VAX/VMS reports a device timeout because the printer did 
not request a hardware interrupt within a specified period of 
time. 

Normally, the LP11 prints the contents of its data buffer and 
requests the interrupt. 


2.8 Handling Interrupts 

When the LP11 printer requests a hardware interrupt, the 
interrupt dispatcher passes the interrupt to the LP11 driver's 
interrupt-servicing routine. 

The driver's interrupt-servicing routine restores control to the 
driver, as follows: 

1 Restores the address of the unit-control block in R5 

2 Confirms that the interrupt was expected by examining bits 
in the device's unit-control block 

3 Restores the saved registers (R3 and R4) from the device's 
unit-control block 

4 Transfers control to the driver PC address stored in the 
device's unit-control block 

Rather than execute in interrupt context, the reactivated driver 
routine calls a VAX/VMS routine to create a driver's fork 
process. VAX/VMS again suspends driver processing by 
performing the following steps: 

1 Saving driver context (R3, R4, and the driver PC address) in 
the device's unit-control block 

2 Inserting the UCB address in the appropriate fork queue 

The driver suspension allows the operating system to 
reschedule driver processing at a lower IPL. A VAX/VMS 
fork dispatcher reactivates the driver when IPL drops to fork 
level. 
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After creating the fork process, the system returns control to 
the driver's interrupt-servicing routine, which performs the 
following steps: 

1 Restores registers saved at the time of the device interrupt 

2 Dismisses the interrupt 


2.9 l/O-Completion Processing by the Driver 

When the VAX/VMS fork dispatcher reactivates the driver's 
fork process, the driver code continues transferring characters 
into the printer data buffer until the transfer is complete. The 
driver code performs the following steps to transfer characters: 

1 It obtains the number of characters left to transfer from the 
unit-control block. 

2 It transfers characters until the LP11 again prints its data 
buffer or all characters have been transferred. 

3 When all characters have been transferred, the driver code 
branches to the driver's I/O-completion code. 

The driver's I/O-completion code stores the following 
information in RO: 

• A success status code 

• The number of bytes transferred 

Then the driver code transfers control to VAX/VMS to complete 
the I/O request. 
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2.10 l/O-Completion Processing by the VAX/VMS System 

The operating system inserts the I/O-request packet into an 
I/O postprocessing queue. If another I/O-request packet is in 
the queue for the device unit, VAX/VMS dequeues that packet 
and calls the driver start-I/O routine to process it. 

When IPL drops to IPL$_IOPOST, the processor grants the 
I/O postprocessing interrupt request. The I/O postprocessing 
dispatcher dequeues the packet for the printer I/O request and 
performs the following steps: 

1 It increases the use count of the process's buffered I/O 
requests because the current operation is complete. The use 
count is maintained for accounting purposes. 

2 It deallocates the system buffer used for the reformatted user 
data. 

3 It increases the process's current byte count quota. 

4 It sets an event flag to indicate that the I/O operation is 
complete. 

5 It queues a kemel-mode-AST routine that will deallocate 
the I/O-request packet and stores I/O status into the user's 
I/O-status block. 

The user process examines the event flag or issues a Wait for 
Single Event Flag system service call to determine that the I/O 
operation is complete. 
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The VAX/VMS operating system uses three mechanisms to 
synchronize I/O processing: 

• Hardware interrupt priority levels and interrupt-servicing 
routines 

• Fork processes of drivers, fork blocks, and fork queues 

• Resource-wait queues 

When programming a driver, you must observe the VAX/VMS 
conventions that govern the use of interrupt priority levels and 
fork processes. The VAX/VMS routines that grant resources to 
drivers enforce the use of resource-wait queues. 


3.1 Interrupt Priority Levels 

The VAX processor defines 32 levels of hardware priorities, 
called interrupt priority levels (IPLs). IPL 0 has the lowest 
priority, and IPL 31 has the highest. Interrupts can be requested 
either by software (software interrupts) or by the hardware 
(hardware interrupts). The system uses the various interrupt 
priority levels as follows: 

• User-mode software runs at IPL 0. 

• Operating system routines and fork processes request 
software interrupts at IPLs 1 through 15. 

• Devices and error conditions generate hardware interrupts at 
IPLs 16 through 31. 

Many IPLs have an interrupt-servicing routine associated with 
them. The processor responds to both software and hardware 
interrupts by transferring control to the appropriate interrupt¬ 
servicing routine. The interrupt-servicing routine processes the 
interrupt and, when finished, dismisses the interrupt with an 
REI instruction. 
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3.1.1 IPLs Defined by VAX/VMS 

Table 3-1 describes the uses that VAX/VMS defines for IPLs 0 
through 15. 


Table 3-1 IPLs Defined by VAX/VMS 


IPL 

Symbolic Name 

Use 

0 

- 

User-mode software 

1 

- 

Reserved 

2 

IPL$_ASTDEL 

Routine that services AST- 
delivery interrupts 

3 

IPL$_SCHED 

Routine that services scheduler 
interrupts 

4 

IPL$_IOPOST 

Routine that services 1/0- 
postprocessing interrupts 

5 

IPL$_XDELTA 

XDELT A-interrupt-servicing 
routine 

6 

IPL$_QUEUEAST 

Fork level processing for 
queuing ASTs 

8 

IPL$_SYNCH 

System database access and 
servicing of 


IPL$_TIMER 

timer interrupts 

8-11 

none 

Fork level for driver execution 

12 - 15 


Reserved 


3.1.2 IPLs Defined for the Hardware 

Hardware interrupt levels are used for device interrupts (IPLs 
20 through 23) and urgent conditions including power failure 
and serious errors such as a machine check. The VAX Hardware 
Handbook provides additional information about hardware 
interrupt levels. 
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3.1.3 


Interrupt-Servicing Routines 

The VAX/VMS operating system uses interrupt-servicing 
routines that gain control at the IPLs described above. This 
use guarantees that interrupts are processed according to the 
following priorities: 

• Device interrupts (highest priority) 

• Device drivers' fork processes 

• I/O postprocessing 

• Process scheduling 

• AST delivery (lowest priority) 

For example, VAX/VMS completes the processing of an 
I/O request by placing the I/O-request packet in the I/O 
postprocessing queue and requesting an interrupt at the I/O 
postprocessing IPL (IPL 4). When the interrupt priority level 
drops below 4, the processor grants the software interrupt by 
transferring control to the I/O postprocessing routine. 

Interrupt-servicing routines run in a reduced context. The stack 
is a special stack used only during interrupt processing; it is the 
interrupt stack. Of the register set, usually only RO through R5 
are saved. The interrupt-servicing routine must restore these 
registers before it returns from an interrupt. 

If the interrupt-servicing routine uses any registers other than 
RO through R5, the routine must save the registers before 
use and restore them after use. Using registers other than RO 
through R5 is not recommended. 

When a hardware interrupt occurs, the system transfers control 
to the driver's interrupt-servicing routine with IPL set to the 
device interrupt level. Because code executing at IPLs 20 
through 23 blocks most other hardware interrupts and all 
software interrupts, driver code lowers its IPL as soon as 
possible. 

The operating system allows the creation of a fork process so 
that a driver can continue execution without blocking other 
device interrupts. Section 3.2 discusses fork processes. 
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3.1.4 Raising IPL 

Code running in kernel mode can raise its IPL to lock out 
context switching and to block interrupts. VAX/VMS software- 
interrupt-servicing routines perform some of their processing 
at IPLs higher than the IPL at which the routines gain control. 
For example, the scheduler is an interrupt-servicing routine that 
gains control at IPL 3; however, it raises IPL to 7 to read and 
modify the system database. 

Drivers typically raise IPL to check for a power failure, to 
send a message to a mailbox, and sometimes to access device 
registers. Driver code should not raise IPL for more than a few 
instructions because doing so blocks all interrupts at lower IPLs. 


3.1.5 Lowering IPL 

Once an interrupt-servicing routine has received the interrupt, it 
transfers control to the main flow of driver code. At this point, 
the driver is executing in the context of an interrupt-servicing 
routine and at device IPL. 

When a driver gains control, it might execute a few instructions 
at device IPL; however, almost immediately a driver lowers IPL 
to fork IPL. A driver lowers IPL by invoking the VAX/VMS 
macro that creates fork processes, IOFORK. As a result of 
invoking IOFORK, VAX/VMS performs the following functions 
for the driver: 

• Consults the device's unit-control block to determine fork 
IPL for the driver 

• Creates a driver's fork process and queues it for execution at 
the appropriate IPL 

• Requests a software interrupt at that IPL 

When the queued fork process is activated, it executes at the 
lower, fork IPL. Section 3.2 describes fork-process dispatching 
in greater detail. 

Fork processes can also modify IPL by invoking certain 
VAX/VMS macros; Section 3.1.11 describes these macros. 
Normally, a driver uses these macros to raise IPL before 
initiating a transfer. 
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3.1.6 Dispatching Device Interrupts 

VAX peripheral devices request interrupts at IPLs 20 through 
23. When a device requests an interrupt at one of these IPLs 
and the processor is executing at a lower IPL, the processor 
performs two steps: 

• It grants the interrupt. 

• It transfers control to an interrupt-servicing routine for the 
device. 

If the processor is executing at a higher or equal IPL, the 
interrupt remains pending. 

The dispatching of UNIBUS device interrupts differs depending 
upon the type of processor and UNIBUS adapter in the 
hardware configuration. 

When an interrupt occurs on a configuration that uses the 
nondirect vector UNIBUS adapter, the processor transfers 
control to an interrupt-servicing routine for the UNIBUS 
adapter of the device that requested the interrupt. The 
UNIBUS adapter's interrupt-servicing routine then carries 
out the following steps: 

1 Saves R0 through R5 on the interrupt stack. 

2 Reads a UNIBUS adapter register to determine the vector 
address of the device requesting the interrupt. 

3 Uses the vector address as an index into a vector-jump table 
within the adapter-control block. The vector-jump table 
contains a list of addresses within channel-request blocks 
that point to the interrupt-servicing routines for all the 
devices attached to that UNIBUS. 

4 Transfers control to the channel-request block (CRB) address 
that corresponds to the vector address. 

The CRB address contains a JSB instruction that passes control 
to the device's interrupt-servicing routine. Figure 3-1 shows 
a flowchart that details the dispatching of a nondirect-vector 
interrupt. 
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On a configuration that supports direct-vector interrupts, the 
UNIBUS adapter does not dispatch the interrupt. Instead, the 
processor locates the device's interrupt-servicing routine by 
using the system-control block (SCB). 

The system-control block consists of two or three pages of 
addresses. Page one lists the exception vectors; pages two 
and three contain the list of CRB addresses that point to the 
interrupt-servicing routines for devices attached to the first 
UNIBUS and an optional second UNIBUS, respectively. The 
SCB base register (SCBB), an internal processor register, marks 
the base of the system-control block. 

The processor obtains the vector address of the device that 
requested the interrupt and uses it as an index into page two 
(or page three) of the SCB. When it finds the corresponding 
CRB address, the processor transfers control to the interrupt¬ 
dispatching code in the device's channel-request block. On 
direct-vector configurations, the interrupt-dispatching code is a 
PUSHR instruction of RO through R5 followed by the JSB to the 
device's interrupt-servicing routine. 

Figure 3-2 shows a flowchart of interrupt dispatching on a 
direct-vector UNIBUS adapter. 

To maintain machine-independent descriptions of interrupt 
handling, subsequent chapters in this manual refer to the 
combination of hardware and software that transfers device 
interrupts to the device's interrupt-servicing routine as the 
interrupt dispatcher. 


3.1.7 Transferring Control to the Fork Process 

When a device driver receives an expected interrupt from 
a device, the driver interrupt-servicing routine executes in the 
context of an interrupt; it is not executing in fork process context 
at that point. Interrupt context has the following characteristics: 


• IPL is elevated to the level at which the device requests 
hardware interrupts. 

• The stack is the interrupt stack. 

• The top of the stack contains a pointer to the address of the 
controller's interrupt-dispatch block (IDB), which contains 
the address of the control/status register. 
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• The stack also contains saved RO through R5 and the PC 
and PSL of the interrupted code. 

The interrupt occurs either because the device has completed 
an I/O operation or because an error occurred during the I/O 
operation. A driver's interrupt-servicing routines generally 
determine whether to service the interrupt by examining the 
I/O database. If the unit-control block for the device that 
currently owns the controller indicates that the interrupt is 
expected, the interrupt-servicing routine takes the following 
steps to transfer control to the driver's start-I/O routine: 

• Loads the address of the UCB into R5 

• Restores the contents of two registers (R3 and R4) from the 
UCB's fork block 

• Returns control to the saved PC in that fork block 

The driver might need to execute a few instructions in the 
context of the interrupt. For example, the driver might copy 
device-status information from the device's registers into the 
device's unit-control block. After executing these instructions at 
device IPL, the driver completes the I/O processing at a lower 
priority by creating a fork process, as described in Section 3.2. 


3.1.8 IPL Use During I/O Processing 

I/O processing occurs mainly at the following IPLs: 

• IPL$_ASTDEL (IPL 2) 

• IPL$__IOPOST (IPL 4) 

• fork-processing IPLs (IPLs 8 through 11) 

• Hardware device IPLs (IPLs 20 through 23) 

• IPL$_POWER (IPL 31) 
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Figure 3-1 Dispatching a Nondirect-Vector Interrupt 
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3.1.8.1 IPL$_ASTDEL (IPL 2) 

IPL$_ASTDEL blocks the delivery of asynchronous system 
traps (ASTs). When a system service for which an AST was 
specified is completed, the system service queues the AST and 
causes a software interrupt to be requested at IPL$_ASTDEL. 
The AST delivery interrupt-servicing routine gains control 
when IPL drops below IPL$_ASTDEL. It delivers the AST to 
the process that is currently scheduled. 

Any driver routine that allocates or deallocates dynamic system 
pool space while running in the context of a process (for 
example, an FDT routine) must do so at an IPL of IPL$_ 
ASTDEL or higher. 

The VAX/VMS allocation routine records the address of the 
allocated system memory in a register. If an AST that aborts 
the process were to occur, the allocated memory would be 
lost from the pool. To block ASTs, I/O preprocessing, from 
the time that the Queue-I/O-Request system service allocates 
an I/O-request packet through the execution of the last FDT 
routine, occurs at IPLs no lower than IPL$_ASTDEL. 

A process cannot incur page faults when IPL is above IPL$_ 
ASTDEL. Any code that executes at a higher IPL must refer 
only to nonpaged virtual memory or pages that have been 
locked in virtual memory. A fatal bugcheck occurs if a page 
fault is incurred above IPL$_ASTDEL. 
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Figure 3-2 Dispatching a Direct-Vector Interrupt 
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In addition, some I/O postprocessing occurs in a kernel-mode- 
AST-servicing routine that also executes at IPL$_ASTDEL. 
Kernel-mode ASTs, running in the context of a process whose 
I/O has been completed, write status information into I/O- 
status blocks, copy buffered input into process space, and 
deallocate system buffers. 


3.1.8.2 IPL$_IOPOST (IPL 4) 

I/O postprocessing includes all I/O-completion processing 
that can occur without reference to the device's unit-control 
block and, thus, can occur at an IPL lower than fork IPL. To 
request I/O postprocessing, drivers call a VAX/VMS routine 
that inserts I/O-request packets in the postprocessing queue 
and requests a software interrupt at IPL$_IOPOST. 

I/O postprocessing runs at an IPL higher than IPL$_SCHED so 
that all pending I/O-completion processing is finished before 
the scheduler looks for a new process to schedule. Whether a 
process is awaiting I/O completion affects its ability to execute. 
Because I/O postprocessing queues ASTs to processes, the 
scheduler might preferentially reschedule a waiting process 
because of a pending AST to the process. 

The VAX/VMS operating system performs I/O postprocessing 
in the IPL 4 interrupt-servicing routine. This routine adjusts 
process quota use, queues a kernel-mode AST to write status 
and data into the process's address space, and deallocates 
system memory. 


3.1.8.3 Fork Processing (IPLs 8 through 11) 

Fork processing occurs at an IPL in the range 8 through 11, 
depending on the contents of the unit-control block field 
UCB$B_FIPL. UCB$B_FIPL contains a value that is used as 
that device's fork IPL. All driver routines, except for most FDT 
routines, execute at fork IPL or higher. Usually driver routines 
should not read or alter fields of the unit-control block unless 
IPL is at fork level or higher. 

The only way a driver may lower IPL below the IPL of the 
interrupt that caused the driver to be reentered is by creating a 
fork process at the lower IPL. 

All devices on a single UNIBUS adapter share the same fork IPL 
if they actively compete for shared UNIBUS adapter resources 
such as mapping registers and data paths. 
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3.1.8.4 Hardware Device Interrupts (IPLs 20 through 23) 

The UCB$B_DIPL field in the device's unit-control block 
contains an IPL value at which the device requests hardware 
interrupts. This IPL is in the range 20 through 23 because 
device interrupts usually need to interrupt most user and 
VAX/VMS software functions. IPLs 20 through 23 correspond 
to UNIBUS bus request (BR) levels 4 through 7. Device drivers 
sometimes raise IPL to UCB$B_DIPL or higher before reading 
and writing certain device registers. 


3.1.8.5 IPL$_POWER (IPL 31) 

The highest IPL, IPL$_POWER, locks out all other interrupts. 
Many VAX/VMS routines and drivers raise IPL to IPL$_ 
POWER to execute code sequences that cannot tolerate 
interruption. For example, much of system initialization occurs 
at IPL$_POWER. 

When a device driver needs to execute a series of instructions 
without interruption, the driver raises IPL to IPL$_POWER. 
The driver never should remain at IPL$_POWER for more than 
a few instructions. The most common instance of a driver's 
raising IPL to IPL$_POWER is to determine whether a power 
failure has occurred between the time that the driver writes 
set-up data into device registers and the time that the driver 
starts the device by writing into the device's control register. 


3.1.9 Additional IPLs 

In addition to the IPLs described above, VAX/VMS defines the 
following: 

• IPL$_SCHED (IPL 3), which is never used by drivers 

• IPL$_QUEUEAST (IPL 6), which is very seldom used by 
drivers 

• IPL$_SYNCH and IPL$_TIMER (IPL 8) 

• IPL$_MAILBOX (IPL 11), which is very seldom used by 
drivers 

For debugging purposes, the VAX/VMS operating system 
defines the priority level IPL$_XDELTA (IPL 5); it is described 
in Section 3.1.9.5. 
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3.1.9.1 IPL$_SCHED (IPL 3) 

When the system wishes to reschedule processes, a VAX/VMS 
routine requests a software interrupt at IPL$_SCHED. The 
scheduler interrupt-servicing routine gains control at this IPL. 

If a process raises IPL to or above IPL$_SCHED, the scheduler 
cannot reschedule the processor. The process runs until an 
interrupt occurs at a higher IPL or the process reduces IPL 
below IPL$_SCHED. 


3.1.9.2 IPL$_QUEUEAST (IPL 6) 

IPL$_QUEUEAST is a fork-level IPL in that the interrupt¬ 
servicing routine for IPL$_QUEUEAST is the fork dispatcher 
that dequeues fork blocks and restores control to fork processes 
that need to execute at IPL$_QUEUEAST. 

To queue an AST, a driver creates a fork process at IPL$_ 
QUEUEAST. When the fork dispatcher restores control to the 
fork process, the process can raise IPL to IPL$_SYNCH and 
queue the AST. 

A driver that wishes to gain access to the system database for 
any reason can also create a fork process at IPL$_QUEUEAST. 
The fork dispatcher restores control to the driver at IPL$_ 
QUEUEAST, and the driver can then raise IPL to IPL$_SYNCH 
(a nonfork IPL) to gain access to the system database. 


3.1.9.3 IPL$_SYNCH and IPL$_TIMER (IPL 8) 

IPL$_SYNCH is the system database synchronization level. 
When a VAX/VMS subroutine or a driver needs to modify or 
read a dynamic portion of the system database, the routine 
always executes at IPL$_SYNCH to ensure that the database 
does not change due to some interrupt-servicing routine or 
process action. 

A timer-queue interrupt-servicing routine fields interrupts 
requested at IPL$_TIMER, which is also IPL 8. The hardware 
clock's interrupt-servicing routine requests a software timer 
interrupt at IPL$_TIMER when the current process has 
exceeded its processor time quantum or when the first entry in 
the timer queue is due. The timer's interrupt-servicing routine 
dequeues the first timer-queue entry and takes appropriate 
action. 
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3.1.9.4 IPL$_MAlLBOX (IPL 11) 

When a VAX/VMS or driver routine writes into a mailbox, 
IPL must be at IPL$_MAILBOX to prevent other writers from 
modifying incomplete data in the mailbox, or readers from 
reading invalid data. 

IPL$_MAILBOX is the highest fork level; drivers can raise IPL 
to IPL$_MAILBOX and write into a mailbox. 


3.1.9.5 IPL$_XDELTA (IPL 5) 

To stop the operating system for debugging purposes, you can 
halt the operating system from the console terminal and request 
a software interrupt at IPL$_XDELTA. The processor must 
be executing below IPL 5 for the interrupt to have an effect. 
Chapter 15 describes the XDELTA debugging program. 


3.1.10 Overview of IPL Use 

Figure 3-3 illustrates the normal IPL flow during the processing 
of an I/O request. 

The user program, executing at IPL 0, issues a Queue-I/O- 
Request system service call. I/O processing by the system 
service and FDT routines occurs mostly at IPL$_ASTDEL. Very 
rarely, an FDT routine raises IPL to fork level to read or modify 
the device's unit-control block. 

The start-I/O routine executes as a fork process at fork IPL, but 
might raise to device IPL or IPL$_POWER for short periods 
of time. After the fork process activates the device, the driver 
calls a VAX/VMS routine that saves the driver's fork context, 
suspends fork processing, and restores IPL to a previous level. 

Figure 3-4 illustrates the completion of the I/O request from 
the point of the device interrupt to the delivery of ASTs to 
the user program. The device interrupts at a device IPL (in 
the range 20 through 23). VAX/VMS transfers control to the 
appropriate driver interrupt-servicing routine. The interrupt¬ 
servicing routine reactivates the driver's fork process with IPL 
still at device IPL. 
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The fork process briefly examines or saves the contents of the 
device's registers, but soon requests that VAX/VMS insert a 
fork block describing its context into one of the fork queues 
for drivers' fork IPLs (8 through 11). When the fork process 
regains control at the driver's fork IPL, the process analyzes 
the success of the I/O operation and writes status into RO and 
Rl. Then, still at fork IPL, VAX/VMS inserts the I/O-request 
packet into the I/O-postprocessing queue and starts the next 
I/O request. 

The I/O postprocessing routine adjusts process-quota usage and 
deallocates system buffers for write functions at IPL$_IOPOST. 
The routine also calls another VAX/VMS routine that raises IPL 
to IPL$_SYNCH to queue a kernel-mode AST to the process 
that issued the original QIO request. 

The kemel-mode-AST routine executes at IPL$_ASTDEL. It can 
queue a user-mode-AST routine that eventually executes at an 
IPL of 0. I/O postprocessing continues at IPL$_IOPOST until 
all entries in the postprocessing queue have been serviced. 


3-15 


Synchronization of I/O-Request Processing 


Figure 3-3 I PL Conventions During I/O Processing 
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3.1.11 Modifying IPL in Driver Code 

The interrupt priority level at which driver code executes 
changes as a result of either of the following events: 

• The driver's calling a VAX/VMS routine that raises or 
lowers IPL 

• The driver's invoking a VAX/VMS macro to request 
explicitly a change in IPL 
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Subsequent chapters of this manual discuss the VAX/VMS 
routines that change IPL; discussions include their expectation 
of IPL at entry and their IPL setting at exit. The sections that 
follow describe the macros that drivers can call to change IPL: 

• SETIPL 

• DSBINT 

• ENBINT 

• SOFTINT 


Figure 3-4 IPL Conventions During I/O Completion 
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3.1.11.1 Set-Interrupt-Priority-Level Macro 

The Set-Interrupt-Priority-Level (SETIPL) macro moves the 
specified IPL into the IPL processor register. 

Format 

SETIPL [ipl] 

ipl 

The interrupt priority level. If no priority level is specified, the 
macro moves the value 31 into the IPL register. Setting IPL to 
31 blocks all interrupts. 


3.1.11.2 Disable-Interrupts Macro 

The Disable-Interrupts (DSBINT) macro saves the current IPL 
in the specified destination and moves the specified IPL into the 
IPL processor register. Procedures invoke this macro to raise 
IPL. 

Format 

DSBINT [ipl] [,dst] 

ipl 

The interrupt priority level. The macro saves the current IPL 
on the top of the stack (default) or in the specified destination 
and moves the specified IPL into the IPL register. If IPL is not 
specified, the macro moves the value 31 into the IPL processor 
register; this blocks all interrupts. 

dst 

The location in which the current IPL is to be saved. If this 
argument is not specified, the current IPL is stored on the top 
of the stack by default. 


3.1.11.3 Enable-Interrupts Macro 

The Enable-Interrupts (ENBINT) macro restores an IPL value 
to the IPL processor register. Procedures invoke this macro to 
lower IPL to a previously saved level. If an interrupt is pending 
at an intermediate IPL (one lower than the current IPL but 
higher than the specified IPL), restoring IPL causes immediate 
interruption of the current procedure. 
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Format 

ENBINT [src] 

src 

The location containing the IPL to be restored. If this argument 
is not specified, the macro moves the IPL value contained on 
the top of the stack into the IPL register. 


3.1.11.4 Software-Interrupt Macro 

The Software-Interrupt (SOFTINT) macro moves the specified 
IPL into the software interrupt request processor register to 
request a software interrupt. 

If the processor is executing at a low IPL (for example, IPL 
0) and detects a software interrupt request at a higher IPL (1 
through 15), the processor immediately transfers control to a 
software interrupt-servicing routine for the appropriate IPL. 

If the processor is executing at or above the specified IPL, the 
processor does not transfer control to the software interrupt¬ 
servicing routine until IPL drops below the specified IPL. 

Format 

SOFTINT ipl 

ipl 

The interrupt priority level at which the software interrupt is 
being requested. 


3.2 Fork Blocks and Fork Dispatching 

Device-driver routines that activate a device and complete an 
I/O operation after a device interrupt execute for relatively 
short periods of time. Execution might be suspended to wait 
for a device interrupt or shared resources. To ensure that the 
resulting context-switching is fast, VAX/VMS forces driver 
routines to execute in a minimal, fork process context consisting 
of a device's UCB, called a fork block, and a few registers. 

Fork processes are created in either of the following situations: 

• Once the preprocessing of an I/O-request packet has been 
performed, a VAX/VMS routine creates a fork process to 
execute the driver's start-I/O routine. If the driver is already 
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3.2.1 


busy, the VAX/VMS routine queues the I/O-request packet 
for the driver to process later. 

• Either the driver's interrupt-servicing routine or the driver 
postprocessing routine creates a fork process to perform 
device-dependent I/O postprocessing. 

When the system creates a fork process to execute the start-I/O 
routine, the newly created fork process can execute immediately 
because the I/O-request packet has been preprocessed by the 
Queue-I/O-Request system service and driver's FDT routines, 
and because the device is idle. 

When the driver's interrupt-servicing routine or the driver's 
postprocessing routine creates a fork process, it does so to lower 
the IPL at which the driver's code is executing. Either the 
interrupt-servicing routine or the start-I/O routine invokes the 
VAX/VMS macro IOFORK. 

IOFORK saves the context needed for the driver to execute as 
a fork process, inserts the driver's UCB fork block in the fork 
queue for the driver's IPL, and requests a software interrupt for 
that IPL. 


Interrupt-Servicing Routine for Fork Dispatching 

One interrupt-servicing routine handles all fork-process 
dispatching. When the processor grants an interrupt at fork 
IPL, the fork dispatcher saves RO through R5 on the stack and 
processes the fork queue that corresponds to the IPL of the 
interrupt. To do so, it removes an entry from the fork queue, 
restores the fork process context, and reactivates the suspended 
fork process. 

When that fork process is completed, the dispatcher regains 
control, removes the next entry, if any, from the queue, restores 
its fork process context, and reactivates it. 

This sequence is repeated until the fork queue is empty. When 
the queue is empty, the fork dispatcher restores RO through 
R5 from the stack and dismisses the interrupt with an REI 
instruction. 

Figure 3-5 illustrates the fork queue structure. 
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A newly activated fork process executes under the following 

constraints: 

• It cannot refer to the address space of the process initiating 
the I/O request. 

• It can use only RO through R5 freely; it must save other 
registers before use and restore them after use. Use of 
registers other than RO through R5 is strongly discouraged. 

• It must clean up the stack after use; the stack must be in its 
original state when the fork process relinquishes control to 
any VAX/VMS routine. 

• It must execute at IPLs between the driver's fork IPL and 
IPL$_POWER; it must not lower IPL below the driver's fork 
IPL except by creating a fork process at a lower IPL. 

• When it returns control to the fork dispatcher, IPL must be 
the same as it was when the fork process was activated. The 
driver returns control to the fork dispatcher by invoking the 
wait for interrupt macro or the request complete macro. 
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Figure 3-5 Fork Dispatching Data Structure 
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3.3 Resource-Wait Queues 

The processing of an I/O request often requires shared system 
resources such as memory and UNIBUS adapter mapping 
registers. The Queue-I/O-Request system service and fork 
processes call VAX/VMS routines to allocate and deallocate 
these resources. Because the resources are limited, I/O 
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processing might be delayed until unavailable resources are 
released by other processes or drivers. Thus synchronization of 
access to these resources can have a substantial impact on the 
processing of I/O requests. 

For example, the Queue-I/O-Request system service calls a 
VAX/VMS routine to allocate nonpaged system space for an 
I/O-request packet. If the nonpaged pool is empty, the routine 
calls another VAX/VMS routine to save the process context 
and change the process state to resource-wait mode (also called 
miscellaneous wait, or MW AIT). As a result of waiting, the 
process is a candidate to be swapped out of memory. When 
nonpaged pool becomes available, the scheduler reschedules 
the process. 

During fork process execution at elevated IPLs, driver context is 
very small. At any point, the driver can obtain all details about 
an I/O request by referring to the I/O database. The driver 
needs only the address of the device's unit-control block, which 
is the key to the rest of the database. Therefore, VAX/VMS 
routines that control driver resources, such as UBA mapping 
registers, use fork blocks and resource-wait queues to save 
minimal driver context. Each entry in a queue consists of the 
following items: 

• The address of the UCB, which is also the contents of R5 
in the fork process; the UCB also contains the driver's fork 
block 

• R3, and normally R4, from the fork process 

• A PC for the waiting fork process 

When the awaited resource becomes available, the routine 
controlling the resource performs the following steps: 

• Restores the UCB address to R5 

• Restores the saved registers R3 and R4 

• Grants the resource 

• Transfers control to the saved driver return PC address 
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3.3.1 


Because the VAX/VMS routine that controls a particular 
resource places the driver in a waiting state when the driver 
requests an unavailable resource, drivers are unaware of 
execution being suspended and subsequently reactivated. 
Drivers must not leave anything on the stack when calling a 
routine that might suspend the driver's execution. 


Competing for a Controller's Data Channel 

A controller's data channel is a VAX/VMS synchronization 
mechanism that guarantees for multiunit controllers that one 
unit uses the controller at a time. A device's fork process can 
read and write a device's registers whenever the device unit 
owns the controller's data channel. 

Devices that share a controller, such as disk units, own the 
controller's data channel only when a VAX/VMS routine 
assigns the channel to the unit's fork process. In contrast, a 
single device unit on a controller always owns the controller's 
data channel. Therefore, if VAX/VMS transfers control to such 
a driver's start-I/O routine, the driver can immediately address 
the device's registers without first obtaining the controller's data 
channel. 

An LP11 printer, such as the one discussed in Chapter 2, has 
a dedicated (single-unit) controller attached to the UNIBUS. 
When VAX/VMS finds the device idle and creates a printer 
driver's fork process to write data to the printer's data buffer, 
the controller's data channel is guaranteed not to be busy. 
Because the data channel is not busy, the driver's start-I/O 
routine can perform the following: 

1 Retrieve the virtual address of the data to be written and the 
number of bytes to transfer from the device's unit-control 
block 

2 Retrieve the virtual address of the device's control/status 
register from the interrupt-dispatch block 

3 Calculate the address of the line printer's data buffer register 
by adding a constant offset to the control/status register 
address 
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4 Write data one byte at a time to the line printer's data buffer 
until all bytes of data have been written 

In contrast, a device unit on a multiunit controller must compete 
for the controller's data channel with other devices attached to 
that controller. 

An RK611 controller, for example, controls as many as eight 
RK06/RK07 devices. The disk driver's fork process must gain 
control of the controller's data channel before starting an I/O 
operation on the unit associated with the fork process. The disk 
driver's start-I/O routine uses the following sequence to start a 
seek operation on an RK07 device: 

1 The start-I/O routine requests the controller's data channel 
by invoking a VAX/VMS channel arbitration routine. 

2 The VAX/VMS routine tests the CRB mask field to 
determine whether the controller's data channel is available. 

3 If the channel is available, the VAX/VMS routine allocates 
the channel to the fork process and returns the address of 
the device's control/status register to the fork process. 

If the channel is busy, the VAX/VMS routine saves the 
driver fork context in the UCB fork block and inserts the 
fork block address in the controller's channel-wait queue. 

4 When the fork process resumes execution, the process owns 
the controller channel. The fork process can then modify 
the device's registers to activate the device. 

5 The driver's start-I/O routine then requests VAX/VMS to 
suspend driver processing in anticipation of an interrupt or 
timeout and to release the channel. 

6 The VAX/VMS channel releasing routine assigns channel 
ownership to the next fork process in the channel-wait 
queue, loads the control/status register address into a 
general register, and reactivates the suspended fork process. 

7 The reactivated fork process continues execution as though 
the channel had been available in the first place. 
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The VAX/VMS channel-arbitration routines keep track of 
controller availability using a flag-field in the channel-request 
block. The fork process must always request and release the 
controller's data channel by invoking these routines. Once the 
driver owns a controller's data channel, the driver is free to 
read and modify the device's registers. 
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The UNIBUS adapter connects the UNIBUS, an asynchronous, 
bidirectional bus, to the backplane interconnect. The adapter 
performs the following functions: 

• Arbitrates priority interrupts from UNIBUS devices 

• Delivers interrupts from UNIBUS devices to the processor 

• Allows drivers to gain access to UNIBUS device's registers 
using system virtual addresses 

• Translates 18-bit UNIBUS addresses to physical addresses 

• Provides a data-transfer path to randomly ordered physical 
pages 

• Provides buffered data transfer paths to consecutively 
increasing physical addresses 

• Permits byte-aligned buffers for UNIBUS devices requiring 
word-aligned buffer addresses 

Together the UNIBUS adapter and the backplane interconnect 
permit devices and device drivers to exchange data without 
much awareness of the intervening hardware. Because 
VAX/VMS routines handle the details of the interface between 
the adapter and the backplane interconnect, most device drivers 
do not need to know the interface protocol. 

The critical responsibility of UNIBUS device drivers that 
actively compete for shared UNIBUS adapter resources is 
that they all execute at the same fork IPL. This IPL convention 
synchronizes access to the UNIBUS adapter data structures. 

In general, device drivers use the UNIBUS adapter for the 
following purposes: 

• Reading and writing device registers 

• Mapping UNIBUS addresses to physical addresses and vice 
versa for direct-memory-access (DMA) transfers 
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• Buffering data transfers 

Drivers for UNIBUS devices that do not perform DMA transfers 
are unaware of the presence of the UNIBUS adapter. The 
UNIBUS adapter provides access to device registers using 
an address mapping scheme that is invisible to the driver. 
However, drivers that handle DMA transfers to and from 
UNIBUS devices must call VAX/VMS routines that establish 
the appropriate mapping. 


4.1 Reading and Writing Device Registers 

Each I/O controller or device directly attached to the UNIBUS 
has a set of control/status and data registers. These registers 
are assigned addresses in a portion of the physical address 
space called the UNIBUS address space. Device drivers obtain 
the device's status and activate the device by reading and 
writing to these registers. 

Generally, a device driver can treat the addresses of device 
registers as identical to all other virtual addresses. The driver 
can read and write data to the device's register as though the 
device's register were a location in memory. The driver must 
obey the restrictions on instructions described in Section 6.2. 
The UNIBUS adapter performs the mapping of virtual address 
to UNIBUS addresses that correspond to device registers. 

Before a driver for a device that shares a controller can gain 
access to a device's registers, it must first obtain a controller 
channel, as described in Section 3.3.1. 


4.2 Mapping UNIBUS and Physical Addresses for DMA 
Transfers 

The UNIBUS address space consists of 256K bytes of memory, 
of which 8K bytes are reserved for device-control registers. 
UNIBUS DMA devices read and write data from and to memory 
locations using 18-bit UNIBUS addresses. The UNIBUS adapter 
translates the 18-bit UNIBUS addresses into physical addresses. 
This translation allows the operating system, I/O drivers, and 
UNIBUS devices to access the same physical address space. 
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4.2.1 


The UNIBUS adapter provides 496 mapping registers to 
translate UNIBUS addresses to physical addresses. Each 
mapping register represents one page of the UNIBUS address 
space. A field in the mapping register identifies the page- 
frame number corresponding to the UNIBUS address that the 
mapping register represents. 

For example, VAX/VMS routines fill as many mapping 
registers with valid page-frame addresses as needed for a 
DMA transfer. A DMA device puts an address on the UNIBUS. 
The UNIBUS adapter receives the address and translates it 
using the following information: 

• The 9-bit UNIBUS page address field (bits 9 through 17 of 
the UNIBUS address) identifies the UBA mapping register. 

• The page-frame-number field in the mapping register 
specifies the high-order bits of the physical address. 

• UNIBUS address bits 2 through 8 map to bits 0 through 6 of 
the physical address. 

The resulting physical address locates the longword that is the 
target of the transfer. The UNIBUS adapter identifies the byte 
addressed within the longword by interpreting the low-order 
two bits of the UNIBUS address. 

Figure 4-1 illustrates the UNIBUS- to physical-address 
mapping. 

Each UNIBUS adapter mapping register also contains a bit 
called the mapping-register-valid bit. The UNIBUS adapter 
tests this bit every time the mapping register is used. If the bit 
is not set, the UNIBUS adapter aborts the UNIBUS transfer. 
This bit is zero whenever the register is not mapped to a 
physical address. 


UN I BUS Adapter Data Transfer Paths 

The UNIBUS adapter sends data through one of several data 
paths for UNIBUS devices performing DMA transfers. One data 
path, the direct data path (DDP), allows UNIBUS transfers to 
randomly ordered physical addresses. The direct data path 
maps each UNIBUS transfer to a backplane interconnect 
transfer. Thus, a single word or byte of data is transferred 
per backplane interconnect operation. 
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Figure 4-1 UNIBUS- to Physical-Address Mapping 


18-BIT UNIBUS ADDRESS 



PHYSICAL ADDRESS 


ZK-915-82 


The remaining data paths, the buffered data paths (BDPs), 
allow devices on the UNIBUS to transfer much faster than 
through the direct data path. The buffered data paths store 
UNIBUS data so that multiple UNIBUS transfers result in a 
single backplane interconnect transfer. 

The UNIBUS adapter hardware of certain processors restricts 
normal buffered data paths to referring only to consecutively 
increasing addresses. Through a special mode of operation, 
these UNIBUS adapters can also refer to data in a randomly 
ordered, longword-aligned manner. Other processors do not 
impose this restriction. In order for a device driver to run on 
both types of processors, it must observe two rules: 

• Normal buffered data paths must always transfer data to 
consecutively increasing addresses. 

• To reference random longword aligned data, the longword- 
enable bit (LWAE) must be set. 
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When a UNIBUS device begins a DMA transfer by placing 
an address on the UNIBUS, the UNIBUS adapter mapping 
register not only performs address mapping but also provides 
the number of the data path to be used for the transfer. Each 
UNIBUS adapter mapping register contains a field that describes 
the data path. Data path 0 is the direct data path; the other data 
paths are the buffered data paths. 

The sequence below describes a UNIBUS-device DMA transfer. 


1 The UNIBUS device puts an address on the UNIBUS. 

2 The UNIBUS adapter locates the UNIBUS adapter mapping 
register that corresponds to the UNIBUS address. 

3 The UNIBUS adapter verifies that the mapping register has 
the mapping-register-valid bit set. 

4 The UNIBUS adapter maps the UNIBUS address to a 
page-frame number. 

5 The UNIBUS adapter extracts the number of the data path 
to be used for the transfer from the mapping register. 

6 The data path translates the UNIBUS function to a 
backplane interconnect function by reading the UNIBUS 
control lines. 

7 Based on the UNIBUS function indicated by the UNIBUS 
control lines, (DATI, DATIP, DATO, or DATOB), the 
UNIBUS adapter starts appropriate UNIBUS and backplane 
interconnect operations to transfer data to or from the 
UNIBUS device. 
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4.2.1.1 


Direct Data Path 

Since the direct data path performs a backplane interconnect 
transfer for every UNIBUS transfer, the data path can be used 
by more than one UNIBUS device at a time. The UNIBUS 
adapter arbitrates among devices that wish to use the direct 
data path simultaneously. The device driver is unaffected by 
this UNIBUS adapter arbitration. 

The direct data path is slower than buffered data paths 
because each UNIBUS transfer cycle corresponds to a 
backplane interconnect cycle. One word or byte is transferred 
per backplane interconnect cycle. On some hardware 
configurations, the direct data path is unable to transfer a 
word of data to an odd-numbered physical address. Therefore, 
an FDT routine for a DMA device that uses the direct data path 
should check that the specified buffer is on a word boundary. 

UNIBUS devices that transfer data through the direct data path 
do so in order to perform the following functions: 

• Execute an interlock sequence to the backplane interconnect 
(D ATIP-D ATO/DATOB) 

• Transfer to randomly ordered addresses instead of 
consecutively increasing addresses 

• Mix read and write functions 

The direct data path is the simplest data path to program. 
Since the direct data path can be shared simultaneously by any 
number of I/O transfers, the device driver need not allocate 
that data path. Once the mapping registers are loaded, the 
device driver initiates the transfer by setting appropriate bits in 
the device's control register. The programming sequence is as 
follows: 

1 Allocate a set of mapping registers. 

2 Load the mapping registers with physical address mapping 
data and the data path number (0 for the direct data path). 

3 Set the valid bit in every mapping register. The mapping 
register that follows the last mapping register must have the 
valid bit cleared. 

4 Load the starting address of the transfer in a device register. 
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5 Load the transfer byte or word count in a device register. 

6 Set bits in the device control register to initiate the transfer. 

The operating system performs the first three steps above. The 
driver fork process simply calls VAX/VMS routines to allocate 
and load the mapping registers. 


4.2.1.2 Buffered Data Paths 

In contrast to the direct data path, the buffered data paths 
transfer data much more efficiently between the UNIBUS and 
the backplane interconnect by decoupling the UNIBUS transfer 
from the backplane interconnect transfer. Buffered data paths 
read or write multiple words of data in a transfer, and buffer the 
unrequested portions of the data in UNIBUS adapter buffers. 
Thus, several UNIBUS read functions can be accommodated 
with a single backplane interconnect transfer. 

Advantages that buffered data paths offer to UNIBUS devices 
include the following: 

• Fast DMA block transfers to or from consecutively increasing 
addresses 

• Word-oriented block transfers that begin and end on an 
odd-numbered byte of memory; note, however, that these 
transfers can be quite slow because the UNIBUS adapter 
might need to perform multiple transfers to complete a 
1-word transfer 

• 32-bit data transfers from random longword-aligned physical 
addresses 

A buffered data path cannot be assigned to more than one 
active transfer at a time. When a driver fork process is 
preparing to transfer data to or from a UNIBUS device on 
a buffered data path, the driver requests allocation of a free 
buffered data path and a set of UNIBUS adapter mapping 
registers. A VAX/VMS I/O routine writes the number of the 
data path into each of the assigned mapping registers. 

A UNIBUS device transfer over a buffered data path has two 
restrictions: 

• All addresses in a block transfer must be consecutively 
increasing addresses. 
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• All transfers within a block must be of the same function 
type (DATI or DATO/DATOB). 

A buffered data path stores data from the UNIBUS in a buffer 
until multiple words of data have been transferred (except 
in longword-aligned transfer mode; see below). Then, the 
UNIBUS adapter transfers the contents of the buffer to the 
appropriate physical address in a single backplane interconnect 
operation. The procedure for a UNIBUS write operation that 
transfers data to memory is broken into individual steps. 

1 The UNIBUS device transfers one word of data to the 
buffered data path. 

2 The buffered data path stores the word of data and 
completes the UNIBUS cycle. 

3 The buffered data path sets its buffer-not-empty flag to 
indicate that the buffer contains valid data. 

4 The UNIBUS device repeats the first three steps until the 
buffer is full. 

5 When the UNIBUS device addresses the last byte or word 
in the buffer, the UNIBUS adapter recognizes a complete 
data-gathering cycle. 

6 The buffered data path requests a backplane-interconnect- 
write function to write the data from the buffered data path 
to memory. 

7 When the backplane interconnect transfer is complete, the 
buffered data path clears its flag to indicate that the buffer 
no longer contains valid data. 

The procedure for a UNIBUS read function varies according 
to the type of UNIBUS adapter. Some adapters can perform 
a prefetch function, while others cannot. Device drivers that 
adhere to the conventions outlined in this manual will execute 
properly on either type of UNIBUS adapter with no difference 
except that of system throughput. 

The following paragraphs discuss the UNIBUS read operation 
with and without the prefetch function. 
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The prefetch automatically fills the buffer after the contents 
of a buffered data path are transferred to the UNIBUS. The 
prefetch speeds up UNIBUS reads from memory. The steps of 
a UNIBUS read function are listed below. 

1 The UNIBUS device initiates a read operation from a 
buffered data path. 

2 The buffered data path checks to see if its buffers contain 
valid data. 

3 If the buffers do not contain valid data, the buffered data 
path initiates a read function to fill the buffers with data. 
The transfer completes before the UNIBUS adapter begins a 
UNIBUS transfer. 

4 The buffered data path transfers the requested bytes to the 
UNIBUS. Bytes of data that were not transferred to the 
UNIBUS remain in the buffer. 

5 The buffered data path sets its buffer-not-empty flag to 
indicate that the buffers contain valid data. 

6 When the UNIBUS device empties the buffers of the 
buffered data path with a UNIBUS read function that 
accesses the last word of data, the buffered data path clears 
the not-empty flag to indicate that the buffers no longer 
contain valid data. 

7 The buffered data path then initiates a read function to 
prefetch data from memory. 

8 When the transfer is complete, the buffered data path sets 
the buffer-not-empty flag to indicate that the buffers now 
contain valid data. 

The prefetch might attempt to read data beyond the address 
mapped by the final mapping register. To avoid referring 
to memory that does not exist, the VAX/VMS routines that 
allocate and load mapping registers always allocate one extra 
mapping register and clear the mapping-register-valid bit before 
initiating the transfer. When the UNIBUS adapter notices that 
the mapping register for the prefetch is invalid, the UNIBUS 
adapter aborts the prefetch without reporting an error. 
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The steps of a UNIBUS read function without prefetch are listed 

below. 

1 The UNIBUS device initiates a read operation from a 
buffered data path. 

2 The buffered data path checks to see if its buffers contain 
valid data. 

3 If the buffers do not contain valid data, the buffered data 
path initiates a read function to fill the buffers with data. 
The transfer completes before the UNIBUS adapter begins a 
UNIBUS transfer. 

4 The buffered data path transfers the requested bytes to the 
UNIBUS. Bytes of data that were not transferred to the 
UNIBUS remain in the buffer. 


4.2.1.3 Byte-Offset Data Transfers 

Some UNIBUS devices are restricted to transferring integral 
words of data in word-aligned UNIBUS addresses. The 
buffered data paths allow these devices to perform transfers 
to memory that begins and ends on an odd-byte address. 

A byte-offset bit in the mapping registers indicates byte- 
aligned data to the hardware. If the bit is set, the hardware 
increments physical addresses. A VAX/VMS subroutine that 
loads mapping registers determines whether the data is word- 
or byte-aligned and sets the byte offset bit accordingly. 


4.2.1.4 Purging a Buffered Data Path 

Because prefetches can read more data from memory than the 
UNIBUS device wishes to read, driver fork processes must ask 
the UNIBUS adapter to purge the buffered data path when a 
transfer is complete. In addition, a transfer from a device to the 
backplane interconnect can complete with some data left in the 
buffer. The driver must purge the data path to complete the 
transfer. 

The purge guarantees that the data is not transferred to the 
next user of the buffered data path. The driver fork process 
performs the purge by calling a standard VAX/VMS subroutine 
that performs two functions. 

• It tells the hardware to purge the buffered data path register 
owned by the fork process. For a UNIBUS read function. 
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the adapter simply clears the buffer-not-empty flag. For a 
UNIBUS write function, the adapter transfers any data left 
in the data path buffer to VAX memory, then clears the flag. 

• It notifies the driver's fork process of any error that occurs 
during the purge. 

The data path must be purged before the driver releases 
mapping registers or the buffered data path register. 


4.2.1.5 Longword-Aligned, 32-Bit, Random-Access Mode 

Another method of transferring data over a buffered data path 
is in longword-aligned, 32-bit, random-access mode. This mode 
permits a device that reads data from or writes data to memory 
in longword-aligned and longword multiples to use the buffered 
data path for random memory access. 

To ensure that random-access mode works correctly regardless 
of processor type, a buffered data path should not repeatedly 
address the same longword. On certain processors a UNIBUS 
device that polls a single longword, waiting for data, will 
constantly be returned the same data. 

A longword-aligned transfer over a buffered data path is faster 
than a transfer over a direct data path and somewhat slower 
than a normal transfer using a buffered data path. 

To transfer data in the longword-aligned, 32-bit, random-access 
mode, the driver's fork process sets the longword-access-enable 
bit (VEC$V_LWAE) in the channel-request block (CRB) prior 
to loading the mapping registers. The UNIBUS device can then 
perform a read (DATI) or write (DATO) function. 

For a UNIBUS read, the function occurs as follows: 

1 The driver's fork process initiates a read function on the 
UNIBUS device. 

2 The UNIBUS adapter clears the buffer-not-empty flag in the 
assigned buffered data path. 

3 The UNIBUS adapter requests a read-from-memory 
operation on the backplane interconnect. 

4 The UNIBUS adapter stores the longword of data in the 
buffered data path and sets the buffer-not-empty flag. 
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5 The UNIBUS adapter initiates two UNIBUS read operations 
to transfer two words of data. 

For a UNIBUS write, the function occurs as follows: 

1 The driver's fork process initiates a write function on the 
UNIBUS device. 

2 The UNIBUS adapter clears the buffer-not-empty flag in the 
assigned buffered data path. 

3 The UNIBUS adapter requests two write operations to 
transfer two words of data from the UNIBUS device. 

4 The UNIBUS adapter stores the longword of data in the data 
path's buffer and sets the buffer-not-empty flag. 

5 The UNIBUS adapter initiates a backplane interconnect 
write operation. 

6 When the backplane interconnect write operation is 
complete, the UNIBUS adapter clears the buffer-not-empty 
flag. 


4.3 The UNIBUS Adapter on the VAX-11/780, 

VAX-11 /782, and VAX-11 /785 

The UNIBUS adapter on a VAX-11/780, VAX-11/782, or 

VAX-11/785 processor has the following hardware features: 

• One direct data path that does not handle byte offsets. 

• Fifteen buffered data paths that handle byte offsets. Each 
data path has an eight-byte buffer and supports the prefetch 
function and longword, random-access mode. The UNIBUS 
adapter uses extended SBI read or write operations to fill a 
buffered data path. 

• The Synchronous Backplane Interconnect (SBI). The SBI 
uses a 30-bit physical address. 

• 496 mapping registers. 

• Nondirect vector interrupt dispatching. 
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• Longword-aligned, random-access mode. When a data path 
is set to this mode, data prefetch is disabled and only four 
bytes of data are buffered. 

Figure 4-2 shows the fields within the mapping register and 
data path register for the VAX-11/780 UNIBUS adapter. 

Figure 4-2 VAX-11/780, VAX-11/782, VAX-11/785 UNIBUS 
Adapter Registers 
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4.4 The VAX-11/750 UNIBUS Adapter 

The UNIBUS adapter on a VAX-11/750 processor has the 
following hardware features: 

• One direct data path that handles byte offsets. 

• Three buffered data paths that handle byte offsets. Each 
data path has a four-byte buffer. The buffered data paths do 
not perform the prefetch function. 
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• The backplane interconnect. This interconnect uses 24-bit 
physical addresses. 

• 512 mapping registers. The VAX/VMS system uses only 
496 of these registers. 

• Direct-vector interrupt dispatching. 

• Implied longword-aligned, random-access mode. Buffered 
data paths on the VAX-11/750 only buffer four bytes of 
data. Because the data paths do not perform a prefetch, they 
can always reference longwords at random. 

VAX-11/750 buffered data paths do not allow repeated 
references to a longword because of a hardware restriction. 

If a longword is referenced more than once, bad data might 
be returned. To ensure compatibility between processors, 
device drivers can set the LWAE bit to indicate longword 
mode. 

Figure 4-3 shows the fields within the mapping register and the 

data path register for the VAX-11/750 UNIBUS adapter. 


4.5 The VAX-11/730 # VAX-11/725 UNIBUS Adapter 

The UNIBUS adapter on a VAX-11/730 or VAX-11/725 
processor has the following hardware features: 

• One direct data path that handles byte offsets. 

• No buffered data paths. 

• The backplane interconnect. This interconnect uses 24-bit 
physical addresses. 

• 512 mapping registers. The VAX/VMS system uses 496 of 
these registers. 

• Direct vector interrupt dispatching. 

Figure 4-4 shows the fields within the mapping register for 
the VAX-11/730 and VAX-11/725 UNIBUS adapters. These 
adapters do not use a data path register; the register exists for 
compatibility with the other VAX processors and contains only 
zeros. The adapter ignores any data written to this longword. 
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Figure 4-3 VAX-11/750 UNIBUS Adapter Registers 
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Overview of I/O Processing 


Under the VAX/VMS operating system, I/O processing occurs 
in three major phases: 

• I/O request preprocessing 

• Device activation and subsequent handling of the device 
interrupt 

• I/O postprocessing 

When a user process issues an I/O request, the Queue-I/O- 
Request system service gains control. The system service 
coordinates the preprocessing of the I/O request. The last 
driver FDT routine called by the Queue-I/O-Request system 
service calls a VAX/VMS routine that creates a driver fork 
process to execute the driver's start-I/O routine; this is the 
routine that activates the device. 

When the transfer is completed, the device requests an interrupt 
that results in execution of the driver's interrupt-servicing 
routine. This routine handles the interrupt and requests creation 
of a driver fork process to perform device-dependent I/O 
postprocessing. The driver fork process then transfers control to 
the system to perform device-independent I/O postprocessing. 
Figure 5-1 illustrates the sequence of events. 


5.1 Preprocessing an I/O Request 

The Queue-I/O-Request system service performs device¬ 
independent preprocessing of an I/O request and calls driver 
FDT routines to perform device-dependent preprocessing. To 
preprocess an I/O request, the Queue-I/O-Request system 
service takes the following steps: 

• Verifies that the requesting process has assigned a process 
I/O channel to the target device 

• Locates the device driver in the I/O database 

• Validates the I/O-function code 
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• Checks process I/O request quotas 

• Validates the I/O-status block 

• Allocates and sets up the I/O-request packet 

• Calls driver FDT routines to perform device-dependent 
preprocessing 


5.1.1 Process I/O Channel Assignment 

The first step in preprocessing an I/O request is to verify that 
the I/O request specifies a valid process I/O channel. The 
process I/O channel is an entry in a system-maintained process 
table that describes a path of reference from a process to a 
peripheral device unit. Before a program requests I/O to a 
device, the program identifies the target device unit by issuing 
an Assign-I/O-Channel system service call. The Assign-I/O- 
Channel system service performs the following functions: 


• Locates an unused entry in the table of process I/O channels 

• Creates a pointer to the device unit in the table entry for the 
channel 

• Returns a channel-index number to the program 

When the program issues an I/O request, the Queue-I/O- 
Request system service verifies that the channel number 
specified is associated with a device and locates the portion 
of the I/O database that describes the device. Figure 5-2 
illustrates the path from a process channel number to the 
device's unit-control block. 
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Figure 5-1 Sequence of Driver Execution 





FORK PROCESS CONTEXT 
KERNEL OR INTERRUPT 
STACK 



HARDWARE INTERRUPT OCCURS WHEN 
REQUESTED BY DEVICE 


INTERRUPT DISPATCHER ACTIVATES 
INTERRUPT SERVICE ROUTINE 



ZK-918-82 


INTERRUPT CONTEXT 
INTERRUPT STACK 


5-3 








































Overview of I/O Processing 


5.1.2 Locating a Device Driver in the I/O Database 

Using information in the unit-control block, a driver can find 
other I/O data structures associated with the device, including: 

• Channel-request block 1 

• Interrupt-dispatch block 

• Device-data block 


5.1.2.1 Unit-Control Block (UCB) 

The process channel number indirectly points to the unit- 
control block for the target device. The unit-control block 
contains the first in a chain of pointers into the I/O database. 
The pointer chain leads to the addresses of driver tables and 
routines in the driver that handles the target device. 

A unit-control block that describes a device unit exists for 
each device in the system. The unit-control block indicates the 
current state of the device unit by specifying such information 
as: 


• Whether the device is active 

• What I/O request is being processed 

• Where transfer buffers are located 

Because drivers run as fork processes and cannot use process 
address space to store additional context, drivers use the unit- 
control block for temporary data storage during I/O processing. 
Chapter 7 describes how you can allocate additional UCB space 
for storing data or device-dependent driver context. 

The unit-control block also holds the context of a driver fork 
process when VAX/VMS I/O routines suspend the fork process 
to wait for an asynchronous event such as a device interrupt. 


1 Channel-request blocks (CRBs) and channel-control blocks are two separate data structures. It is sometimes 
helpful to think of the channel-request block as the "controller-request" block because it describes the 
hardware controller. The channel-control block, on the other hand, describes a logical path from a process to 
an associated unit-control block. 
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Figure 5-2 Locating the Target Device 
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5.1.2.2 Channel-Request Block (CRB) 

All unit-control blocks describing device units attached to a 
particular controller contain a pointer to a single channel- 
request block. The channel-request block contains the following 
information: 

• Code that transfers control to a driver interrupt-servicing 
routine 

• Addresses of driver's unit and controller initialization 
routines 

• A pointer to the interrupt-dispatch block, which further 
describes the controller 

Controllers can be either multiunit or dedicated. A dedicated 
controller has only one device unit. The VAX/VMS operating 
system does not use the channel-request block to synchronize 
I/O operations for a dedicated controller. The channel-request 
block still is present and used by drivers and operating system 
routines. 

For multiunit controllers, a VAX/VMS routine uses a field in 
the channel-request block to arbitrate pending driver requests 
for the controller. When the system grants ownership of a 
multiunit controller data channel to a driver fork process, the 
fork process can initiate an I/O operation on a device attached 
to that controller. 

The unit-control blocks for devices attached to a multiunit 
controller all contain pointers to the same channel-request 
block; this allows the operating system to manage the controller 
data channel. Figure 5-3 illustrates the data structures required 
to describe three devices on a multiunit controller. 
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Figure 5-3 Data Structures for Three Devices on One Controller 
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5.1.2.3 Interrupt-Dispatch Block (IDB) 

The channel-request block also points to an interrupt-dispatch 
block. The interrupt database contains three critical data 
structure addresses: 

• The address of the UCB of the device unit, if any, that 
currently owns the controller data channel 

• The address of the control/status register (CSR); it is the key 
to access to device registers 

• The address of the adapter-control block (ADP) that 
describes the UNIBUS adapter to which the controller is 
attached 


5.1.2.4 Device-Data Block (DDB) 

All unit-control blocks describing device units attached to a 
single controller contain a pointer to a single device-data block 
(DDB). The device-data block contains two fields that identify 
the device and its driver: 

• The generic device/controller name 

• The name of the device's driver as obtained from the driver- 
prologue table; see Chapters 7 and 14 for the use of the 
driver name 
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Figure 5-4 illustrates the relationship between the data 
structures that describe a group of equivalent devices on two 
separate controllers. 

Figure 5-4 I/O Database for Two Controllers 
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In Figure 5-4, one controller has a single device unit, and 
the other controller has two device units. Devices on both 
controllers share the same driver code. 
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5.1.3 Validating the I/O Function 

Using the I/O data structures described above, the Queue- 
I/O-Request system service locates the address of the driver's 
function-decision table by following a chain of pointers that 
begins in the UCB of the target device. The system service 
follows those pointers as follows: 

UCB --> DDT —> FDT 


The system service then uses data in the function-decision table 
to analyze the I/O function. The service confirms that the 
function specified in the I/O request is a valid function for the 
device. 


5.1.4 Checking Process I/O Request Quotas 

The Queue-I/O-Request system service determines whether the 
I/O request being readied will cause the process to exceed its 
quota for outstanding direct or buffered I/O requests. If the 
process remains under quota, the system service allows it to 
continue I/O preprocessing. 

In the case where quota is exceeded, the Queue-I/O-request 
system service examines its resource wait flag. If the flag is 
clear, the system service aborts the I/O request. 

If the flag is set, the process is placed in a wait state until it 
drops below quota, at which time the $QIO system service 
modifies the process quotas as appropriate for the requested 
operation. 


5.1.5 Validating the l/O-Status Block 

If the I/O request specifies a quadword I/O-status block to 
receive final I/O status information, the Queue-I/O-Request 
system service determines whether the process issuing the 
request has write access to the status-block locations specified. 

If the process has write access, the system service fills the 
quadword with zeros. If the process does not have write access, 
the system service terminates the request with an error status. 
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5.1.6 Allocating and Setting Up an l/O-Request Packet 

If validation of the I/O request succeeds to this point, the 
Queue-I/O-Request system service allocates a block of 
nonpaged system memory to contain an I/O-request packet. 

Before the system service allocates an I/O-request packet, it 
raises the hardware IPL of the processor to IPL$_ASTDEL 
to block any other asynchronous activity in the process. The 
new IPL prevents possible termination of the process; process 
termination would result in the operating system's losing track 
of the system memory allocated for the I/O-request packet. 

The Queue-I/O-Request system service attempts to allocate 
an I/O-request packet from a linked list of preallocated I/O- 
request packets. If no preallocated packets exist, the service 
calls a VAX/VMS routine that allocates an I/O-request packet 
from nonpaged pool. This allocating routine synchronizes 
with the rest of the system so that it can allocate the memory 
needed. 

The Queue-I/O-Request system service continues I/O 
preprocessing by writing the following description of the 
I/O request into the packet: 

• Size in bytes of the I/O-request packet 

• A type field identifying the block as an I/O-request packet 

• Access mode of the process at the time of the I/O request 

• Process identification of the requesting process 

• If specified in the I/O request, the address of an AST routine 
and its parameter 

• If the device is file-structured, the address of a control 
block that describes the physical location of part of the file 
(window-control block) 

• Address of the target device's unit-control block 

• I/O-function code; read- and write-virtual-block functions 
are reduced to their equivalent read- and write-logical-block 
functions before storing a code 

• Number of event flag to set when I/O processing is 
complete for the I/O request 

• Base software priority of the requesting process 
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• If specified in the I/O request, the address of an I/O-status 
block 

• Process I/O channel index number 

• A flag indicating whether the I/O function is for buffered or 
direct I/O 

• A flag indicating whether the I/O request is an input request 

• A flag indicating whether the process has privilege to 
perform logical or physical I/O functions 

• A flag indicating whether the I/O function is a physical-I/O 
function 

• If specified in the I/O request, the address and size of a 
diagnostic buffer and a flag indicating that the buffer is 
present 

• If an AST routine is specified in the I/O request, a flag 
indicating that the process quota for the use of ASTs has 
been modified 

The Queue-I/O-Request system service writes the above fields 

in the I/O-request packet because these fields contain device¬ 
independent data. Driver routines or VAX/VMS common 

FDT routines must fill in the device-dependent portions of the 

I/O-request packet. 

Appendix A illustrates the format of an I/O-request packet. 


5.1.7 FDT Processing 

The driver's function-decision table controls the device¬ 
dependent preprocessing of an I/O request. Figure 5-5 
illustrates the format of a function-decision table. 

The I/O-function code specified in an I/O request is a 16-bit 
value consisting of two fields: 

• A 6-bit I/O-function code (bits 0 through 5) 

• A 10-bit I/O-function modifier (bits 6 through 15) 


The 6-bit function-code field permits you to define 64 unique 
I/O function codes for every device type. Chapter 7 describes 
how you can define these function codes. 
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Figure 5-5 Function-Decision Table 
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Because each driver can define up to 64 unique I/O-function 
codes, the first two entries of a function-decision table are two 
longwords (64 bits) each. The first entry is a bit mask of all 
valid I/O-function codes for the device. Each bit represents 
a unique function code. The second entry is a bit mask of 
those valid functions that are also buffered I/O functions. The 
Queue-I/O-Request system service uses these two bit-masks to 
determine whether the I/O-function code is valid and whether 
the operation is to be buffered or direct I/O. 
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The remaining entries of a function-decision table are three 
longwords each. The first two longwords form a bit mask 
of I/O-function codes. The third longword is the address 
of an I/O preprocessing routine to be called for the I/O- 
function codes whose corresponding bits are set in the first two 
longwords. 

The Queue-I/O-Request system service uses the value of 
the low-order six bits of the I/O-function code to determine 
which bit to check in each FDT bit mask. For example, if a 
function code has a value of 22, the system service checks the 
twenty-third bit (bit 22) of each bit mask. 

Some of the preprocessing routines are present in the operating 
system because they provide device-independent services. 
Chapter 8 describes these routines. Other routines are in the 
driver because they perform device-dependent services. 

The Queue-I/O-Request system service uses the 3-longword 
entries in the function-decision table to call I/O preprocessing 
routines in the driver or system, as follows: 

1 In the FDT entry, if the bit corresponding to the value 
of the function code is set, the system service calls the 
associated preprocessing routine, the address of which is in 
the longword following the bit-mask. 

2 If the bit corresponding to the I/O-function code's value is 
not set, the Queue-I/O-Request system service advances to 
the next FDT entry bit mask and repeats the step above. 

3 When the preprocessing routine completes its activity, 
the routine either returns control to the system service or 
transfers control to a VAX/VMS routine that queues the 
I/O-request packet or completes the request. 

4 If the Queue-I/O-Request system service regains control, the 
routine advances to the next FDT entry and repeats the first 
step above. 

5 If all preprocessing for the I/O function is complete, the 
preprocessing routine does not return to the Queue-I/O- 
Request system service. Instead, the routine transfers control 
to either a VAX/VMS routine that queues the I/O request 
for the driver's start-I/O routine or a VAX/VMS routine to 
complete or abort the request. 
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FDT routines used in I/O preprocessing, as illustrated in 
Figure 5-6, must end the Queue-I/O-Request system service's 
scan of the function-decision table. For each valid I/O-function 
code for a device, one FDT entry must end I/O preprocessing. 

FDT routines execute in the context of the process that 
requested the I/O operation. Thus, FDT routines can 
gain access to process virtual address space. Once all FDT 
preprocessing is complete, however, the rest of the processing 
for the I/O request continues in the limited context of a driver 
fork process or an interrupt-servicing routine. 


5.2 Handling Device Activity 

When I/O preprocessing is complete, but the I/O operation 
is not yet complete, an FDT routine transfers control to 
a VAX/VMS routine that queues I/O-request packets and 
arbitrates device activity. The arbitration routine ensures that 
it creates only one driver fork process at a time for each device 
unit on the system. One fork process handles one I/O-request 
packet. 


5.2.1 Creating a Driver Fork Process to Start-I/O 

The routine that queues I/O-request packets determines 
whether a driver fork process exists for the target device, as 
follows: 

• If the device is idle, no driver fork process exists for the 
device; in this case, the queuing routine immediately creates 
a driver fork process to execute the start-I/O routine and 
transfers control to it. 

• If the device is busy, a driver fork process already exists 
for the device; in this case, the queuing routine inserts the 
I/O-request packet into a queue of I/O-request packets 
waiting for the device unit. The routine queues the packet 
according to the base priority of the caller. Within each 
priority, packets are in first-in/first-out order. 

In the latter case, by the time the driver's start-I/O routine 
gains control to dequeue the I/O-request packet, the originating 
user's process context is no longer available. The driver must 
execute in the reduced context of a driver fork process. Because 
the context of the process initiating the I/O request is not 


5—14 







Overview of I/O Processing 


Figure 5-6 FDT Routines and I/O Preprocessing 
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guaranteed to a driver's start-I/O routine, the VAX/VMS 
routine that queues I/O-request packets always initiates the 
driver's start-I/O routine with a context that is appropriate for a 
fork process. The driver fork process consists of three registers 
(or fewer) and a PC. 

The routine that queues I/O-request packets establishes this 
context in the following steps: 

1 It raises IPL to driver fork IPL. 

2 It loads the address of the I/O-request packet into R3. 

3 It loads the address of the device's unit-control block into 
R5. 

4 It transfers control to the driver's start-I/O routine entry 
point using a JMP instruction. 

The newly activated driver fork process executes under the 
following constraints: 

• It cannot refer to the address space of the process initiating 
the I/O request. 

• It can use only RO through R5 freely. It must save other 
registers before use and restore them after use. 

• It must clean up the stack after use. The stack must be in its 
original state when the fork process relinquishes control to 
any VAX/VMS routine. 

• It must execute at IPLs between driver fork level and IPL$_ 
POWER. It must not lower IPL below fork IPL except by 
creating a fork process at a lower IPL. 

Each driver fork process executes until one of the following 
events occurs: 

• Device-dependent processing of the I/O request is complete. 

• A shared resource needed by the driver is unavailable, as 
described in Section 3.3. 

• Device activity requires the fork process to wait for a device 
interrupt. 
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5 . 2.2 


Activating a Device and Waiting for an Interrupt 

A device driver's start-I/O routine examines the I/O-request 
packet to determine the type of I/O operation to perform and 
the I/O request specification. Depending on the device type 
supported by the driver, the start-I/O routine performs some or 
all of the following steps: 

• Analyzes the I/O function and branches to driver code that 
prepares the unit-control block and the device for that I/O 
operation 

• Copies the contents of fields in the I/O-request packet into 
the unit-control block 

• Tests fields in the unit-control block to determine whether 
the device and/or volume mounted on the device are valid 

• If the device is attached to a multiunit controller, obtains the 
controller data channel 

• If the I/O operation is a DMA transfer, obtains a UNIBUS 
adapter data path and loads UNIBUS adapter mapping 
registers 

• Loads all necessary device registers except for the device's 
control/status register 

• Raises IPL to IPL$_POWER and confirms that a power 
failure that would invalidate the device operation has not 
occurred 

• Loads the device's control/status register to activate the 
device 

• Invokes a VAX/VMS routine to suspend the driver fork 
process until a device interrupt or timeout occurs 

While the driver is suspended, the context saved for it consists 
of the unit-control block. The context contains the following 
information: 

• A description of the I/O request and the state of the device 

• The contents of R3 and R4 

• The implicit contents of R5 as the address of the unit-control 
block 

• A driver return address 
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5 . 2.3 


• The address of a device timeout handler 

• The time at which the device will time out 

By convention, R4 often contains the address of the control 
/status register (CSR); it permits the driver to examine device 
registers. When the driver fork process regains control after 
interrupt processing, R5 contains the UCB address; it is the key 
to the rest of the I/O database that is relevant to the current 
I/O operation. 


Handling a Device Interrupt 

Once the driver's start-I/O routine initiates the transfer, the 
driver invokes a VAX/VMS routine to wait for an interrupt. 
When the device requests an interrupt, the interrupt dispatcher 
transfers control to the driver interrupt-servicing routine. The 
driver's interrupt-servicing routine runs at a high interrupt 
priority level so that the routine can service interrupts quickly. 
A driver interrupt-servicing routine usually performs the 
following processing: 

1 For multiunit device controllers, determines which device 
unit generated the interrupt 

2 Examines the unit-control block for the device to confirm 
that the driver fork process expects the interrupt 

3 Saves device registers 

4 Reactivates the suspended driver fork process 

If necessary, the reactivated driver fork process executes at the 
high IPL of the interrupt-servicing routine for a few instructions. 
Very soon, however, the driver lowers its execution priority so 
that it does not block subsequent interrupts for other devices in 
the system. 
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5.2.4 Switching from Interrupt to Fork Process Context 

To lower its priority, the driver calls a VAX/VMS fork process 
queuing routine (IOFORK) that performs the following steps: 

1 Disables the timeout that was specified in the wait-for- 
interrupt routine 

2 Saves R3 and R4 (these are the registers needed to execute 
as a fork process) 

3 Saves the address of the instruction following the IOFORK 
request in the UCB fork block 

4 Places the address of the UCB fork block from R5 in a fork 
queue for the driver's fork level 

5 Returns to the driver's interrupt-servicing routine 

The interrupt-servicing routine then cleans up the stack, restores 
registers, and dismisses the interrupt. Figure 5-7 illustrates the 
flow of control in a driver that creates a fork process after a 
device interrupt. 

Figure 5-7 Creating a Fork Process After an Interrupt 
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5.2.5 Activating a Fork Process from a Fork Queue 

When no hardware interrupts are pending, the software 
interrupt priority arbitration logic of the processor transfers 
control to the software interrupt fork dispatcher. When the 
processor grants an interrupt at a fork IPL, the fork dispatcher 
processes the fork queue that corresponds to the IPL of the 
interrupt. To do so, the dispatcher performs these: 

1 It removes a driver fork block from the fork queue. 

2 It restores fork context. 

3 It transfers control back to the fork process. 

Thus, the driver code calls VAX/VMS code that coordinates 
suspension and restoration of a driver fork process. This 
convention allows VAX/VMS to service hardware device 
interrupts in a timely manner and reactivate driver fork 
processes as soon as no device requires attention. 

When a given fork process completes execution, the fork 
dispatcher removes the next entry, if any, from the fork 
queue, restores its fork process context, and reactivates it. 

This sequence is repeated until the fork queue is empty. When 
the queue is empty, the fork dispatcher restores RO through 
R5 from the stack and dismisses the interrupt with an REI 
instruction. 

Figure 5-8 illustrates the reactivation of a driver fork process. 


5.3 Completion of an I/O Request 

Once reactivated, a driver fork process completes the I/O 
request as follows: 

1 Releases shared driver resources such as UNIBUS adapter 
and mapping registers and ownership of the controller 

2 Returns status to the VAX/VMS I/O completion routine 
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Figure 5-8 Reactivation of a Driver Fork Process 
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The I/O-completion routine performs the following steps to 
start postprocessing of the I/O request and to start processing 
the next I/O request in the device's queue: 
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5.3.1 


1 Writes return status from the driver into the I/O-request 
packet 

2 Inserts the finished I/O-request packet in the I/O- 
postprocessing fork-queue and requests an interrupt at 
IPL$_IOPOST 

3 Creates a new fork process for the next I/O-request packet 
in the device's pending-I/O queue 

4 Activates the new driver fork process 


I/O Postprocessing 

When processor priority drops below the I/O postprocessing 
IPL, the processor dispatches to the I/O postprocessing 
interrupt-servicing routine. This VAX/VMS routine completes 
device-independent processing of the I/O request. 

Using the I/O-request packet as a source of information, the 
I/O postprocessing dispatcher executes the sequence below for 
each I/O-request packet in the postprocessing queue: 

1 Removes the I/O-request packet from the queue 

2 If the I/O function was a direct I/O function, adjusts the 
recorded use of the issuing process's direct I/O quota and 
unlocks the pages involved in the I/O transfer 

3 If the I/O function was a buffered I/O function, adjusts the 
recorded use of the issuing process's buffered I/O quota 
and, if the I/O was a write function, deallocates the system 
buffers used in the transfer 

4 Posts the event flag associated with the I/O request 

5 Queues a kemel-mode-AST routine to the process that 
issued the Queue-I/O-Request system service call 

The queuing of a kemel-mode-AST routine allows I/O 
postprocessing to execute in the context of the user process 
but in a privileged access mode. Process context is needed to 
return the results of the I/O operation to the process's address 
space. The kemel-mode-AST routine writes the following data 
into the process's address space: 
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• Data read in a buffered I/O operation 

• If specified in the I/O request, the contents of the diagnostic 
buffer 

• If specified in the I/O request, the two longwords of I/O 
status 

If the I/O request specifies a user-mode-AST routine, the 
kernel-mode-AST routine queues the user-mode AST for the 
process. When VAX/VMS delivers the user-mode AST, the 
system AST delivery routine deallocates the I/O-request packet. 
The first part of an I/O-request packet is the AST-control block 
for user requested ASTs. 
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Device drivers consist of static tables, routines that perform 
I/O preprocessing, and routines that handle the device and 
controller. The chapters that follow describe how to write the 
following sections of a driver: 

• Static tables 

• Routines that use the device driver's function-decision table 
(FDT) 

• Routines that start an I/O operation on the device and 
complete the I/O operation 

• Routines that handle interrupts 

• Routines that request allocation of UNIBUS adapter mapping 
registers and data paths 

• Routines that initialize devices and controllers 

• Routines that cancel an I/O operation 

• Routines that log errors 

The "how to" chapters are preceded by a chapter that contains 
a driver template. The template illustrates the general 
organization and writing of a driver. 

Note that the "how to" chapters describe a common approach 
to the design of various driver routines; they are examples. 
They do not present the only approach that can be taken to 
writing a driver. 
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The pages that follow describe conventions to be used by 
device drivers and provide a template for a device driver. 
Drivers do not necessarily need all of the routines indicated by 
the template, nor do driver routines and tables need to follow 
the exact order of the template. However, the VAX/VMS 
operating system does place a few restrictions on the order and 
content of driver routines and tables. 

Figure 6-1 illustrates the organization of a device driver. 

The first item in a device driver is the driver-prologue table. 
This table must be the first part of a driver. The order of the 
remaining tables and routines varies from driver to driver. 

The last statement in every driver, except for the .END 
assembly directive, must be a label marking the end of 
the driver. The address of this label is stored in the driver- 
prologue table. The driver-loading procedure uses this address 
to calculate the size of the driver. Chapter 14 describes the 
driver-loading procedure. 

Some drivers contain no device-dependent, function-decision- 
table routines. Other drivers need only minimal initialization 
procedures. However, every driver normally contains static 
driver tables and a start-I/O routine or an interrupt-servicing 
routine. 


6.1 Coding Conventions 

The driver-loading procedure loads a device driver into a block 
of nonpaged system memory whose location is chosen by the 
operating system memory allocation routines. Therefore, the 
driver must consist of position-independent code only. 

In addition, the system might call a device driver repeatedly 
to process I/O requests and interrupts. The driver often does 
not complete one I/O operation before the system transfers 
control to the driver to begin another on a different unit. For 
this reason, the code must be reentrant. 
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The rules of position-independent and reentrant code are listed 

below. 

• Instructions can branch only to relative addresses within 
the driver and to global addresses listed in the VAX/VMS 
symbol table (SYS$SYSTEM:SYS.STB). 

• Static tables can list only relative addresses within the driver 
and global addresses. 

• The driver cannot store temporary data in local driver 
tables for dynamic driver context. All dynamic temporary 
storage must be contained within the unit-control block 
corresponding to an I/O request or the current I/O-request 
block. 

• The driver must refer to the I/O database by loading the 
address of a data structure into a general register and using 
displacement addressing to the fields of the data structure. 


Device drivers must also restrict their use of general registers 

and the stack: 

• FDT routines can use RO through R2 and R9 through Rll 
as available registers. The routines can use other registers 
by saving the registers before use and restoring them before 
exiting from the FDT routine. 

• All other driver routines can use RO through R5 as available 
registers. The routines can use other registers, if necessary, 
by saving and restoring them; but using other registers in 
this way is discouraged. 

• All driver routines can use the stack for temporary storage 
only if the routines restore the stack to its previous state 
before calling any VAX/VMS routines or executing RSB 
instructions. 
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Figure 6—1 Driver Organization 


DRIVER 

PROLOGUE 

TABLE 


DRIVER 

DISPATCH 

TABLE 


FUNCTION 

DECISION 

TABLE 


FDT 

ROUTINES 


DEVICE HANDLING 
ROUTINES 


END MARK 
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6.2 Restrictions on the Use of Device-Register I/O Space 

The programmer of a device driver for a UNIBUS device 
must observe the following restrictions on the use of a device 
registers: 

• Drivers should always store the address of a device control 
register in a general register and then gain access to the 
device register indirectly through the general register. The 
example below defines symbolic word offsets for each device 
register and gains access to them using displacement-mode 
addressing from R4. 

; Device register offsets 

LP.CSR = 0 
LP.DBR = 2 


MOVL 

MOVL 


TSTW LP_CSR(R4) ; Is printer online? 

• Floating, double, field, queue, or quadword operands are not 
allowed in I/O address space, nor can an instruction obtain 
the position, size, length, or base of an operand from I/O 
space. For example, a driver cannot use a field instruction to 
test a bit in a device register. 

• Drivers cannot use string-handling instructions. 

• Drivers can use only those instructions that modify or write 
to a maximum of one destination. The destination must be 
the last operand. 

• Registers of devices connected to the backplane interconnect 
(for example, UNIBUS adapter device registers and 
MASSBUS device registers) are longwords. Registers of 
devices connected to the UNIBUS are words. Instructions 
that refer to UNIBUS adapter registers must use longword 
context. All driver instructions that affect UNIBUS device 
registers must use word context, for example, BISW, MOVW, 
and ADDW3, unless the register is byte-addressable. 


UCB$L_CRB(R5),R4 
CRB$L_INTD+VEC$L_IDB(R4),R4 


Get address of CRB 
Get the address of 
the device'8 CSR 


; CSR offset 
; Buffer address offset 
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• An instruction that refers to I/O space must not generate 
an exception or be interrupted. If the instruction is allowed 
to restart, it will re-read the device register, which causes 
undesirable device side-effects or data loss. 


• To access I/O space, use the instructions listed below. 
These instructions cannot be interrupted unless they use 
autoincrement-deferred addressing mode or any of the 
displacement-deferred modes when specifying an operand. 


ADAWI 

ADD(B,W,L)2 

ADD(B,W,L)3 

ADWC 

BIC(B,W,L)2 

BIC(B,W,L)3 

BICPSW 

BIS(B,W,L)2 

BIS(B,W,L)3 

BISPSL 

BISPSW 

BIT(B,W,L) 

CASE(B,W,L) 

CHM(K,E,S,U) 

CLR(B,W,L) 

CMP(B,W,L) 

CVT(BW,BL,WB, 

WL,LB,LW) 

DEC(B,W,L) 

INC(B,W,L) 


MCOM(B,W,L) 

MFPR 

MNEG(B,W,L) 

MOV(B,W,L) 

MOVA(B,W,L) 

MOVAQ 

MOVPSL 

MOVZ(BW,BL,WL) 

MTPR 

PROBE(R,W) 

PUSHA(B,W,L) 

PUSHAQ 

PUSHL 

SBWC 

SUB(B,W,L)2 

SUB(B,W,L)3 

TST(B,W / L) 

XOR(B / W / L)2 

XOR(B,W,L)3 


The following pages list the VAX/VMS template driver. A 
machine-readable copy is also available. Its file specification is 
S Y S$EX AMPLES: TDRIVER. MAR. 
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.TITLE TDRIVER - VAX/VMS TEMPLATE DRIVER 
.IDENT 'V04-002' 

Copyright (c) 1978,1979,1980, 1982, 1984 

by DIGITAL Equipment Corporation, Maynard, Massachusetts 

This software is furnished under a license and may be used and copied 
only in accordance with the terms of such license and with the 
inclusion of the above copyright notice. This software or any other 
copies thereof may not be provided or otherwise made available to any 
other person. No title to and ownership of the software is hereby 
transferred. 

The information in this software is subject to change without notice 
and should not be construed as a commitment by DIGITAL Equipment 
Corporation. 

DIGITAL assumes no responsibility for the use or reliability of its 
software on equipment which is not supplied by DIGITAL. 


++ 

FACILITY: 

VAX/VMS Template driver 
ABSTRACT: 

This module contains the outline of a driver: 

Models of driver tables 

Controller and unit initialization routines 

An FDT routine 

The start-I/O routine 

The interrupt-servicing routine 

The cancel I/O routine 

The device register dump routine 

AUTHOR: 

S. Programmer 11-N0V-1979 
REVISION HISTORY: 


V02 JHP001 J. Programmer 2-Aug-1979 11:27 

Remove BLBC instruction from CANCEL routine. 

V02-001 JHP001 J. Programmer ll-Feb-1981 13:10 

Add description of reason argument to CANCEL 
routine. Correct references to channel index 
number. 


6-6 






Template for an I/O Driver 



V04-001 JHP001 D. Programmer 24-May-1984 17:53 

Add $DYNDEF, $VADEF, $FCBDEF, 

$PCBDEF, $PRVDEF, $RNSDEF. 


.SBTTL External and local symbol definitions 



External symbols 

SCANDEF 

$CRBDEF 

$DCDEF 

$DDBDEF 

SDEVDEF 

$DYNDEF 

$FCBDEF 

SIDBDEF 

$I0DEF 

$IPLDEF 

SIRPDEF 

SPCBDEF 

$PRVDEF 

SRNSDEF 

SSSDEF 

$UCBDEF 

SVADEF 

$VECDEF 


Cancel reason codes 
Channel request block 
Device classes and types 
Device data block 
Device characteristics 
Dynamic-data-structure types 

Interrupt dispatch block 
I/O function codes 
Hardware IPL definitions 
I/O-request packet 
PCB offsets 
Privilege definitions 

System status codes 
unit-control block 
Virtual address definitions 
Interrupt vector block 


Local symbols 


Argument list (AP) offsets for device-dependent QIO parameters 


PI 

= 

0 

First QIO parameter 

P2 

= 

4 

Second QIO parameter 

P3 

= 

8 

Third QIO parameter 

P4 

= 

12 

Fourth QIO parameter 

P5 

= 

16 

Fifth QIO parameter 

P6 


20 

Sixth QIO parameter 

; Other 

constants 




TD_DEF_BUFSIZ 

TD_TIMEOUT_SEC 

TD_NUM_REGS 


= 1024 
= 10 
= 4 


Default buffer size 
10 second device timeout 
Device has 4 registers 
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Definitions that follow the standard UCB fields 


SDEFINI UCB 
.=UCB$K_LENGTH 

$DEF UCB$W_TD_WORD 

.BLKW 1 


$DEF UCB$W_TD_STATUS 

.BLKW 1 


$DEF UCB$W_TD_WRDCNT 

.BLKW 1 


$DEF UCB$W_TD_BUF ADR 

.BLKW 1 


$DEF UCB$W_TD_DATBUF 

.BLKW 1 

$DEF UCB$K_TD_UCBLEN 


; Start of UCB definitions 
; Position at end of UCB 

; A sample word 

; Device's CSR register 

; Device's word count register 

; Device's buffer address 
; register 

; Device's data buffer register 
; Length of extended UCB 


Bit positions for device-dependent status field in UCB 


$VIELD UCB,0,<- 

<BIT_ZERO,,M>,- 
<BIT_ONE,,M>,- 
> 


Device status 
First bit 
Second bit 


$DEFEND UCB 


; End of UCB definitions 


Device register offsets from CSR address 


$DEFINI TD 
$DEF TD.STATUS 


.BLKW 1 


; Start of status definitions 
; Control/status 
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Bit positions for device control/status register 



_VIELD TD_STS, 0, <- 

Control/status register 

<G0,,M>,- 

Start device 

<BIT1,,M>,- 

Bit one 

<BIT2,,M>,- 

; Bit two 

<BIT3,,M>,- ; 

; Bit three 

<XBA,2,M>,- ; 

; Extended address bits 

<INTEN,,M>,- 

Enable interrupts 

<READY,,M>,- 

Device ready for command 

<BIT8,,M>,- 

Bit eight 

<BIT9,,M>,- ; 

; Bit nine 

<BIT10,,M>,- 

; Bit ten 

<BIT11,,M>,~ 

; Bit eleven 


Disregarded bit 

<ATTN,, M>, - 

Attention bit 

<NEX,,M>,- 

Nonexistent memory flag 

<ERROR,,M>, - 

> 

Error or external interrupt 

$DEF TD.WRDCNT 

; Word count 

.BLKW 1 


$DEF TD_BUFADR 

; Buffer address 

.BLKW 1 


$DEF TD.DATBUF 

; Data buffer 

.BLKW 1 


$DEFEND TD 

; End of device register 


; definitions. 

.SBTTL Standard tables 


; Driver prologue table 


DPTAB 

; DPT-creation macro 

END=TD_END,- 

; End of driver label 

ADAPTER=UBA,- 

; Adapter type 


UCBSIZE=<UCB$K_TD_UCBLEN>. 
NAME=TDDRIVER 


Length of UCB 
Driver name 
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DPT.STORE INIT 


DPT.STORE UCB,UCB$B_FIPL,B,8 
DPT.STORE UCB,UCB$B_DIPL,B,22 
DPT.STORE UCB,UCB$L_DEVCHAR, L, <- 
DEV$M_IDV!- 
DEV$M_0DV> 


DPT.STORE UCB,UCB$B_DEVCLASS,B,DC$_SCOM 
DPT.STORE UCB,UCB$W_DEVBUFSIZ,W,- 
TD_DEF_BUFSIZ 


DPT.STORE REINIT 


DPT.STORE DDB,DDB$L_DDT,D,TD$DDT 
DPT.STORE CRB,CRB$L_INTD+4, D, - 
TD_INTERRUPT 


DPT.STORE CRB,- 

CRB$L_INTD+VEC$L_INITIAL,- 
D,TD.CONTROL.INIT 


DPT.STORE CRB,- 

CRB$L_INTD+VEC$L_UNITINIT,- 
D,TD.UNIT.INIT 


DPT.STORE END 


Driver dispatch table 
DDTAB 

DEVNAM=TD.- 
START=TD_START,- 
FUNCTB=TD_FUNCTABLE,- 
CANCEL=TD_CANCEL,- 
REGDMP=TD_REG_DUMP 


Start of load 
initialization table 


Device fork IPL 
Device interrupt IPL 
Device characteristics 
input device 
output device 

; Sample device class 
; Default buffer size 


; Start of reload 
; initialization table 


Address of DDT 
Address of interrupt 
service routine 


; Address of controller 
; initialization routine 


Address of device 
unit initialization 
routine 


; End of initialization 
; tables 


DDT-creation macro 
Name of device 
Start-I/O routine 
FDT address 
Cancel I/O routine 
Register dump routine 
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Function decision table 


TD.FUNCTABLE: 

FDT for driver 

FUNCTAB ,- 

Valid I/O functions 

<READVBLK,- 

Read virtual 

READLBLK,- 

Read logical 

READPBLK,- 

Read physical 

WRITEVBLK,- 

Write virtual 

WRITELBLK,- 

Write logical 

WRITEPBLK,- 

Write physical 

SETMODE,- 

Set device mode 

SETCHAR> 

Set device chars. 


FUNCTAB , 

No buffered functions 

FUNCTAB +EXE$READ,- 

FDT read routine for 

<READVBLK,- 

read virtual, 

READLBLK,- 

read logical, 

READPBLK> 

and read physical. 


FUNCTAB +EXE$WRITE,- 

; FDT write routine for 

<WRITEVBLK,- 

; write virtual. 

WRITELBLK,- 

; write logical, 

WRITEPBLK> 

; and write physical. 


FUNCTAB +EXE$SETMODE,- 

; FDT 

set mode routine 

<SETCHAR,- 

; for 

set chars, and 

SETMODE> 

; set 

mode. 


.SBTTL TD_CONTROL_INIT, Controller initialization routine 


++ 

TD_CONTROL_INIT, Readies controller for I/O operations 
Functional description: 

The operating system calls this routine in three places: 
At system startup 

During driver loading and reloading 
During recovery from a power failure 
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Input8: 


R4 

- address 

of 

the 

CSR 

R5 

- address 

of 

the 

IDB 

R6 

- address 

of 

the 

DDB 

R8 

- address 

of 

the 

CRB 


(controller status register) 
(interrupt dispatch block) 
(device data block) 

(channel request block) 


Outputs: 

The routine must preserve all registers except R0-R3. 


TD_CONTROL_INIT: 
RSB 


; Initialize controller 
; Return 


.SBTTL TD_UNIT_INIT, Unit initialization routine 


++ 

TD_UNIT_INIT, Readies unit for I/O operations 
Functional description: 

The operating system calls this routine after calling the 
controller initialization routine: 

at system startup 

during driver loading 

during recovery from a power failure 


Input8: 

R4 - address of the CSR (controller status register) 

R5 - address of the UCB (unit-control block) 


Outputs: 

The routine must preserve all registers except R0-R3. 
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TD_UNIT_INIT: 

BISW #UCB$M_ONLINE, 
UCB$W_STS(R5) 

RSB 


Initialize unit 

Set unit online 
Return 


.SBTTL TD_FDT_ROUTINE, Sample FDT routine 


++ 

TD_FDT_ROUTINE, Sample FDT routine 
Functional description: 

SUPPLIED BY USER 


Inputs: 

R0-R2 - scratch registers 

R3 - address of the IRP (I/O-request packet) 

R4 - address of the PCB (process control block) 



R5 

R6 

R7 

R8 

R9-R11 

AP 


- address of the UCB (unit-control block) 

- address of the CCB (channel control block) 

- bit number of the I/O function code 

- address of the FDT table entry for this routine 

- scratch registers 

- address of the 1st function dependent QIO parameter 


Outputs: 


The routine must preserve all registers except R0-R2, and 
R9-R11. 


TD_FDT_ROUTINE: ; Sample FDT routine 

RSB ; Return 

.SBTTL TD.START, Start-I/O routine 


++ 

TD_START - Start a transmit, receive, or set mode operation 



Functional description: 
SUPPLIED BY USER 
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Inputs: 

R3 - address of the IRP (I/O-request packet) 

R5 - address of the UCB (unit-control block) 


Outputs: 

RO - 1st longword of I/O status: contains status code and 

number of bytes transferred 
R1 - 2nd longword of I/O status: device-dependent 

The routine must preserve all registers except R0-R2 and R4. 


TD.START: ; 

WFIKPCH TD_TIMEOUT,#TD_TIMEOUT_SEC 


Process an I/O packet 


After a transfer completes successfully, return the number of bytes 
transferred and a success status code. 


IOFORK 

INSV UCB$W_BCNT(R5).#16.- 

#16,RO 

MOVW #SS$_NORMAL,RO 


; Call I/O postprocessing. 

COMPLETE.10: 

REQCOM 


Load number of bytes trans¬ 
ferred into high word of RO. 
Load a success code into RO. 


; Driver processing is finished 
; Complete I/O. 


Device timeout handling. Return an error status code. 


TD.TIMEOUT: 

SETIPL 

UCB$B_FIPL(R5) 

; Timeout handling 
; Lower to driver fork IPL 

MOVZWL 

#SS$_TIMEOUT,RO 

; Return error status. 

BRB 

COMPLETE.10 

; Call I/O postprocessing. 

.SBTTL 

TD_INTERRUPT, Interrupt 

service routine 
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++ 

TD_INTERRUPT, Analyzes interrupts, processes solicited interrupts 
Functional description: 


The sample code assumes either 

that the driver is for a single-unit controller, and 
that the unit initialization code has stored the 
address of the UCB in the IDB; or 

that the driver's start-I/O routine acquired the 
controller's channel with a REQPCHANL macro call, and 
then invoked the WFIKPCH macro to keep the channel 
while waiting for an interrupt. 


Inputs: 



O(SP) 

4(SP) 
8(SP) 
12(SP) 
16(SP) 
20(SP) 
24(SP) 
28(SP) 
32(SP) 


- pointer to the address of the IDB (interrupt dispatch 
block) 

- saved RO 

- saved R1 

- saved R2 

- saved R3 

- saved R4 

- saved R5 

- saved PSL (program status longword) 

- saved PC 


The IDB contains the CSR address and the UCB address. 


Outputs: 

The routine must preserve all registers except R0-R5. 


TD_INTERRUPT: 


MOVL 

<3(SP) + ,R4 

MOVL 

IDB$L_OWNER(R4),R5 

MOVL 

IDB$L_CSR(R4),R4 

BBCC 

#UCB$V_INT,- 


UCB$W_STS(R5),- 


UNS0L_INTERRUPT 



Service device interrupt 
Get address of IDB and remove 
pointer from stack. 

Get address of device owner's 
UCB. 

Get address of device's CSR. 
If device does not expect 
interrupt, dismiss it. 
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This is a solicited interrupt. Save 
the contents of the device registers 

MOVW TD_STATUS(R4),- 

UCB$W_TD_STATUS(R5) 
MOVW TD_WRDCNT(R4),- 

UCB$W_TD_WRDCNT(R5) 
MOVW TD_BUFADR(R4),- 

UCB$W_TD_BUFADR(R5) 
MOVW TD.DATBUF(R4),- 

UCB$W_TD_DATBUF(R5) 


in the UCB. 

; Otherwise, save all device 
; registers. First the CSR. 

; Save the word count register. 

; Save the buffer address 
; register. 

; Save the data buffer register 


Restore control to the main driver. 


RESTORE.DRIVER: 

MOVL UCB$L_FR3(R5).R3 

JSB <3UCB$L_FPC(R5) 


Jump to main driver code. 
Restore driver's R3 (use a 
MOVQ to restore R3-R4). 
Call driver at interrupt 
wait address. 


Dismiss the interrupt. 


UNSOL_INTERRUPT: 

POPR #~M<RO,R1,R2,R3,R4,R5> 
RE I 


Dismiss unsolicited interrupt 

Restore R0-R5 

Return from interrupt. 


.SBTTL TD_CANCEL, Cancel I/O routine 


++ 

TD_CANCEL, Cancels an I/O operation in progress 
Functional description: 

This routine calls IOCSCANCELIO to set the cancel bit in the 
UCB status word if: 

the device is busy, 

the IRP's process ID matches the cancel process ID, 
the IRP channel matches the cancel channel. 

If IOCSCANCELIO sets the cancel bit, then this driver routine 
does device-dependent cancel I/O fixups. 
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Template for an I/O Driver 



Input8: 


R2 

- channel 

R3 

- address 

R4 

- address 


process 

R5 

- address 

R8 

- cancel 


CAN$C_CANCEL 

CAN$C_DASSGN 


if called through $CANCEL or 
$DALL0C system service 
if called through $DASSGN 
system service 


Outputs: 

The routine must preserve all registers except R0-R3. 
The routine may set the UCB$M_CANCEL bit in UCB$W_STS. 



TD.CANCEL: 

JSB 

BBC 


G~IOCSCANCELIO 
#UCB$V_CANCEL,- 
UCB$W_STS(R5),10$ 


Cancel an I/O operation 
Set cancel bit if appropriate. 
If the cancel bit is not set, 
just return. 


Device-dependent cancel operations go next. 


; Finally, the return. 

10 $: 

RSB ; Return 

.SBTTL TD_REG_DUMP, Device register dump routine 


++ 

TD_REG_DUMP, Dumps the contents of device registers to a buffer 
Functional description: 



Writes the number of device registers, and their current 
contents into a diagnostic or error buffer. 
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Inputs: 

RO - address of the output buffer 

R4 - address of the CSR (controller status register) 

R5 - address of the UCB (unit-control block) 


Outputs: 

The routine must preserve all registers except R1-R3. 

The output buffer contains the current contents of the device 
registers. RO contains the address of the next empty longword in 
the output buffer. 


TD_REG_DUMP: 


MOVZBL 

#TD_NUM_REGS,(R0)+ 

MOVZWL 

UCB$W_TD_STATUS(R5),- 
(RO)-*- 

MOVZWL 

UCB$W_TD_WRDCNT(R5) 
(RO) + 

MOVZWL 

UCB$W_TD_BUFADR(R5) 
(RO) + 

MOVZWL 

RSB 

UCB$W_TD_DATBUF(R5) 
(RO) + 

.SBTTL 

TD_END, End of driver 


; Dump device registers 
; Store device register count. 

; Store device status register. 

; Store word count register. 

; Store buffer address register. 

; Store data buffer register. 

; Return 


++ 

Label that marks the end of the driver 


TD.END: 

.END 


Last location in driver 


6-18 







Writing Device-Driver Tables 


Every device driver declares three static tables that describe the 
device and driver: 

• Driver-prologue table that describes the device type, driver 
name, and fields in the I/O database to be initialized during 
driver loading and reloading 

• Driver-dispatch table that lists some of the driver's entry 
points to which VAX/VMS transfers control; the channel- 
request block and function-decision table list other entry 
points 

• Function-decision table that lists valid functions of the 
driver and entry points to routines that perform I/O 
preprocessing for each function 

The VAX/VMS operating system provides macros that drivers 
can invoke to create the tables listed above. Descriptions of 
individual tables in the sections that follow also describe the 
macros invoked to create the tables. 

All of the macros described in this chapter are keyword macros. 
Parameter values for such macros can be expressed in the 
following format: 

KEYWORD=parameter-value 

The VAX MACRO and Instruction Set Reference Volume describes 
the syntax rules for keyword macros in detail. The sections that 
follow provide examples of macro usage. 
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7.1 Driver-Prologue Table 

The driver-prologue table (DPT) is the first part of every device 
driver. This table, along with parameters to the SYSGEN 
command that request driver loading, describes the driver to the 
driver-loading procedure. In turn, the driver-loading procedure 
computes the size of the driver, loads it into nonpaged system 
memory, and creates control blocks for the new device(s) in 
the I/O database. Chapter 14 describes how the driver-loading 
procedure decides which control blocks to build for a given 
device. 

Device drivers can pass control-block-initialization information 
to the driver-loading procedure through values stored in the 
driver-prologue table. In addition, the driver-loading procedure 
initializes some fields within the device control blocks using 
information from its own tables. 

Drivers must treat many of the fields initialized by the driver¬ 
loading procedure as read-only fields. These fields are marked 
with an asterisk in Appendix A. 

To create a driver-prologue table, the driver invokes the DPTAB 
macro, described in Section 7.1.1. 

When the DPTAB macro expands, it creates a control block 
that the driver-loading procedure uses to load the driver. The 
loading procedure loads the driver-prologue table and the driver 
together in virtual memory. The loading procedure also links 
the new driver-prologue table into a list of all driver-prologue 
tables known to the system. 

Most device drivers need to initialize certain fields of the 
I/O database with driver-specific values. The DPT_STORE 
macro provides the driver with a means of communicating 
its initialization needs to the driver-loading procedure. When 
invoked, the DPT_STORE macro places information in the 
driver-prologue table that the driver-loading procedure uses to 
load specified values into specified fields. The DPT_STORE 
macro accepts two lists of fields: 

• Fields to be initialized when a CONNECT command caused 
SYSGEN to build the control blocks and when the driver is 
reloaded 
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• Fields to be initialized only when SYSGEN is given the 
RELOAD command, causing the driver to be reloaded 

The DPTAB macro stores the relative addresses of these two 
lists, called initialization and reinitialization data, in the driver- 
prologue table. The list of one or more invocations of the DPT_ 
STORE macro must appear after the DPTAB macro. Section 
7.1.2 describes the format of the DPT_STORE macro. 


Drivers must use the DPT_STORE macro to supply 
initialization data for the following fields: 

UCB$B_FIPL Driver fork IPL 

UCB$B_DIPL Hardware device IPL 

UCB$I_DEVCHAR Device characteristics (see Appendix A) 


The driver also must provide reinitialization data for the device 
data block field DDB$L_DDT and for any of the following 
routine addresses in the channel-request block: 


DDB$I_DDT 

CRB$I_INTD+4 

CRB$I_INTD+VEC$I_INITIAL 

CRB$I_INTD+VEC$I_UNITINIT 


Address of the driver- 
dispatch table 

Entry point to the driver 
interrupt-servicing routine, if 
one exists 

Address of a controller 
initialization routine, if one 
exists 

Address of a device unit 
initialization routine, if one 
exists. This entry point is 
used by UNIBUS devices. 


7.1.1 DPTAB Macro 

The DPTAB macro creates a driver-prologue table. 

Format 

DPTAB end,adapter,[flags].ucbsize,[unload],[maxunits],[defunits], 
[deliver],[vector].name 
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end 

The name of the label at the end of the driver module. 


adapter 

The adapter type. 

UBA = UNIBUS adapter 
MBA = MASSBUS adapter 
DR = DR device 

NULL = No actual device for driver 


flags 

The driver-loader's flags. 


DPT$M_SVP 


DPT$M_ 

NOUNLOAD 


Indicates, when set, that the device requires 
a permanently allocated system page. This 
flag causes the driver-loading procedure 
to allocate a permanent system page-table 
entry for the device. The virtual address of 
the system page-table entry is written into 

the system page field of the UCB (UCB$I_ 

SVPN) during creation of the UCB. Disk 
drivers use this page-table entry during ECC 
error correction. 

Indicates, when set, that the driver cannot 
be reloaded. A system bootstrap must 
occur before drivers with this bit set can be 
reloaded. 


ucbsize 

The size of each unit-control block in bytes. This argument 
is required. This field allows drivers to extend the unit- 
control block to store device-dependent data describing an 
I/O operation. Appendix A provides examples. Driver routines 
and VAX/VMS ECC routines interpret fields in the extended 
part of the unit-control block. The amount that the unit-control 
block is extended is variable for each driver type. 

unload 

The address of a routine to call before the driver is reloaded. 
The driver-loading procedure calls this routine before 
reinitializing all controllers and device units associated with 
the driver. 
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maxunits 

The maximum number of units that this driver supports on a 
controller. This field affects the size of the interrupt-dispatch 
block created by SYSGEN's CONNECT command. If this field 
is omitted, the default is 8 units. You can override the default 
by appending the /MAXUNITS qualifier to the CONNECT 
command. 

defun its 

The number of units created by default for each controller that 
SYSGEN's AUTOCONFIGURE command processes on behalf 
of this driver. The unit numbers created are zero through 
defunits minus one. If the deliver argument to the DPTAB 
macro is omitted, AUTOCONFIGURE creates the number of 
units specified by defunits. If the deliver argument is present, it 
names a unit-delivery routine that AUTOCONFIGURE calls to 
determine whether or not to create each unit automatically. 

deliver 

The address of a unit-delivery routine that AUTOCONFIGURE 
calls to determine which units to configure automatically for the 
device supported by this driver. 

vector 

The address of a driver-specific transfer vector. Use of this 
argument is reserved to DIGITAL. 

name 

The name of the device driver module. The driver-loading 
procedure will permit only one copy of the driver associated 
with the name given in this field to be loaded. By convention, 
a driver name is formed by appending the string DRIVER to 
the 2- alphabetic character generic device name, for example, 
DBDRIVER. 


7.1.2 DPT_STORE Macro 

The DPT_STORE macro either declares an assembly language 
label or describes a field to be initialized. When the macro 
declares a label, the macro has format 1. When the DPT_ 
STORE macro describes a field to be initialized, the macro has 
format 2. 
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Format 1 

DpTSTORE label-name 

label-name 

The name of the label to be declared. It can be one of the 
following: 

INIT Indicates the start of fields to initialize when the driver 

is loaded. 

REINIT Indicates the start of additional fields to initialize when 
the driver is loaded or reloaded. 

END Indicates the end of the two lists. 

Format 2 

Dpi store struc-type,struc-offset,operation,expression, 

[position],[size] 

struc-type 

The type of control block that contains the field to be initialized. 
The type can be one of the following: 


DDB 

Device-data block 

UCB 

Unit-control block 

CRB 

Channel-request block 

IDB 

Interrupt-dispatch block 

struc 

-offset 


The unsigned offset into the control block. The driver-loading 
procedure can initialize only the first 256 bytes of each data 
structure. Unit and controller initialization routines can 
initialize additional data fields. 

operation 

The type of operation to be performed. The type can be one of 
the following: 

B Write a byte value 

W Write a word value 

L Write a longword value 

D Write an address relative to the driver 
V Write a bit field 

The V operation takes the following longword of data and the 
position and size arguments as operands of an INSV instruction. 
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An at sign (@) preceding the operation parameter indicates 
that the expression parameter that follows is the address of the 
initialization data. 

expression 

An expression to be stored in the control block or, if an at sign 
(@) is specified preceding the operation parameter, the address 
of an expression. For example, the following macro indicates 
that DEVICE_CHARS is the address of the data to write into 
the DEVCHAR field of the UCB. 

DPT.STORE UCB,UCB$L_DEVCHAR,QL,DEVICE_CHARS 

position 

The starting bit position within the specified field. This 
parameter is specified only for V operations. 

size 

The number of bits in the field. This parameter is specified only 
for V operations. 


7 . 1.3 


Example of DPTAB and DPT_STORE Macro Use 


The following example invokes the DPTAB macro and DPT_ 
STORE macros to describe a device driver and its database. 


DPTAB - 

END=XX_END,- 
ADAPTER=UBA.- 

UCBSIZE=UCB$K_XX_LENGTH, - 
NAME=XXDRIVER 
DPT_STORE INIT 


DPT.STORE UCB,UCB$B_FIPL,B,8 

DPT.STORE UCB,UCB$L_DEVCHAR,L,- 
<DEV$M_REC- 
!DEV$M_AVL- 
!DEV$M_ODV> 

DPT.STORE UCB.UCB$B_DEVCLASS.B.- 
DC$_XX 

DPT.STORE UCB.UCB$B_DEVTYPE.B.- 
XX$_XL78 

DPT.STORE UCB,UCB$W_DEVBUFSIZ,W, 
132 

DPT.STORE UCB,UCB$B_DIPL,B.22 


Define DPT 

End of driver 

Adapter type 

Size of UCB 

Name of driver module 

Start of control block 

initialization values 

Driver fork IPL 

Device characteristics: 

record-oriented 

available 

output device 

Device class 
Device type 
Default buffer size 
Device IPL 


DPT.STORE REINIT 

DPT_STORE CRB,CRB$L_INTD+4,D,- 
XX_INTERRUPT 


Start of control block 
reinitialization values 
Interrupt service 
routine address 
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DPT.STORE CRB,CRB$L_INTD+VEC$L_UNITINIT,- 


DPT.STORE DDB,DDB$L_DDT,D,XX$DDT 


D,XX_XL78_INIT 


Unit initialization 
routine address 
Address of driver 


DPT_ST0RE END 


dispatch table 
End of field 


initialization 


7.2 Driver Dispatch Table 


The driver dispatch table (DDT) lists some of the entry 
points for driver routines to be called by VAX/VMS for I/O 
processing. Every driver must create a driver dispatch table. 

The routines listed in the DDB can reside in the driver 
module or in a VAX/VMS module. Appendix A describes the 
VAX/VMS device-independent routines that can be specified. 

Device-dependent routines are normally located in the driver 
module. The driver dispatch table contains relative addresses 
for routines located in the driver module and absolute addresses 
for routines located in the operating system. At loading time, 
the driver-loading procedure changes the relative addresses of 
driver routines to absolute addresses. 

The driver creates the driver dispatch table by invoking the 
macro DDTAB. The driver-loading procedure writes the address 
of the driver dispatch table, as specified in a DPT—STORE 
macro, into the device-data block. 


7.2.1 


DDTAB Macro 


The DDTAB macro creates a driver dispatch table. The table 
has a label of devnam$DDT. Just preceding the table, DDTAB 
generates the driver code program section with the following 
statement: 

.PSECT $$$115_DRIVER 

Format 

DDTAB devnam.start,[unsolic].functb,[cancel], 

[regdmp],[diagbf],[erlgbf].[unitinit], 

[altstart],[mntver],[cloneducb] 
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devnam 

The generic name of the device driven by this device driver. 

start 

The address of the driver's start-I/O routine. 

unsolic 

The address of the routine that services unsolicited interrupts 
from the device. This field is used only by MASSBUS devices. 

functb 

The address of the function-decision table for this driver. 

cancel 

The address of the cancel-I/O routine. 

regdmp 

The address of the routine that dumps the device registers to an 
error log buffer or to a diagnostic buffer. 

diagbf 

The length in bytes of the diagnostic buffer used for this device. 


erlgbf 

The length in bytes of the error log buffer used for this device. 

unitinit 

The address of the device initialization routine, if one exists. 
MASSBUS drivers should use this field rather than CRB$L_ 
INTD + VEC$L_UNITINIT. UNIBUS drivers might use either 
one. 

altstart 

The address of the alternate start-I/O routine. To initiate this 
routine, use the VAX/VMS routine EXE$ALTQUEPKT instead 
of EXE$QIODRVPKT. 

mntver 

The address of a VAX/VMS routine that is called at the 
beginning and end of a mount verification operation. If no 
routine is specified, the routine IOC$MNTVER is called. Use 
of this field to call any routine other than IOC$MNTVER is 
reserved to DIGITAL. 
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cloneducb 

The address of a VAX/VMS routine to call when a UCB is 
cloned by the $ASSIGN system service 

The DDTAB macro writes the address of the VAX/VMS routine 
IOC$RETURN into routine address fields of the driver dispatch 
table that are not supplied in the macro invocation (with the 
exception of the mntver argument). IOC$RETURN executes an 
RSB instruction; for further information, refer to Appendix C. 

In the example below, notice that a plus sign ( + ) precedes the 
address of the entry point to the cancel-I/O routine. The plus 
sign indicates that the routine is part of VAX/VMS. No plus 
sign precedes the address of the start-I/O routine because it is 
part of the driver module. Omitting a required plus sign is a 
common error in device drivers. 


7.2.2 Example of a DDTAB Macro 

A sample invocation of the DDTAB macro follows. 

DDTAB DEVNAM=XX,- ; Driver dispatch table 

START=STARTIO,- ; Start the I/O operation 

FUNCTB=FUNCTABLE,- ; Function decision table 

CANCEL=+IOC$CANCELIO ; Cancel I/O 


7.3 Function-Decision Table 

The function-decision table (FDT) lists codes for I/O functions 
that are valid for the device; indicates whether the functions 
are buffered-I/O functions; and specifies routines to perform 
preprocessing for particular functions. Every device driver must 
create a function-decision table containing three or more entries: 


• The list of valid I/O-function codes 

• The list of buffered I/O-function codes 

• One or more entries, each of which specifies all or a subset 
of I/O-function codes and the address of a routine that 
performs I/O preprocessing for those function codes 


If no buffered I/O functions are defined for the device, the 
second entry contains an empty list. 
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7.3.1 


Taken together, the third through last entries in the function- 
decision table specify one or more FDT routines for each valid 
I/O-function code for the device. The FDT routines must 
terminate the I/O preprocessing for each type of function 
by transferring control out of the Queue-I/O-Request system 
service and into a routine that queues the I/O request to a 
driver, inserts the I/O request in the postprocessing queue, or 
aborts the I/O request. 

Refer to Chapter 8 for information on the writing of FDT 
routines. 

Table 7-1 lists the physical-, logical-, and virtual-I/O-function 
codes that a function-decision table most commonly uses. 

A complete list of function codes is contained in the macro 
$IODEF in SYS$LIBRARY:STARLET.MLB. 


Defining Device-Specific Function Codes 

You can also define device-specific function codes by equating 
the name of a device-specific function with the name of a 
function that is irrelevant to the device. The selected codes 
should, however, have a type (logical, physical, or virtual) that 
is appropriate for the function they represent. For example, 
the assembly code that follows defines three device-specific 
physical-I/O-function codes. 

IO$_STARTCLOCK=IO$_ERASETAPE ; Start hardware clock 

IO$_STOPCLOCK=IO$_OFFSET ; Stop hardware clock 

IO$_STARTDATA=IO$_SPACEFILE ; Start data acquisition 

The device driver creates a function-decision table by invoking 
the FUNCTAB macro. Each invocation of the FUNCTAB 
macro creates a 2- or 3-longword entry in the function-decision 
table. The first two invocations create 2-longword entries 
because they specify only function codes; they do not specify 
an accompanying action routine. 

All subsequent invocations of the FUNCTAB macro must 
specify both function codes and the address of a routine that is 
to perform preprocessing for those functions. These invocations 
create 3-longword entries. 
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Table 7-1 


The Queue-I/O-Request system service processes entries in 
the order in which they appear in the function-decision 
table. When a function code is present in more than one 3- 
longword entry, the system service sequentially calls every 
routine specified for the function code until an routine stops the 
scan by aborting, completing, or queuing an I/O request. 


VAX/VMS l/O-Function Codes 


Function 

Physical I/O 


IO$_AVAILABLE 

IO$_DIAGNOSE 

IO$_DRVCLR 

IO$_ER ASET APE 

IOS—NOP 

IO$_OFFSET 

IO$_PACKACK 

IO$_READHEAD 

IO$_READPBLK 

IO$_READPRESET 

IO$_READTRACKD 

IO$_RECAL 

IO$_RELEASE 

IO$_RET CENTER 

IO$_SEARCH 

IO$_SEEK 

IO$_SENSECHAR 

IO$_SETCHAR 

IO$_SPACEFILE 

IO$_SPACERECORD 


Codes Defined 

Set device available 
(required by all disk 
drivers) 

Diagnose 
Drive clear 
Erase tape 
No operation 
Offset read heads 

Pack acknowledge 
(required by all disk 
drivers) 

Read header and 
data 

Read physical block 
Read in preset 
Read track data 
Recalibrate drive 
Release port 

Return to center 
line 

Search for sector 
Seek cylinder 

Sense device 
characteristics 

Set device 
characteristics 

Space files 
Space records 
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Table 7-1 (Cont.) VAX/VMS l/O-Function Codes 


Function 


Codes Defined 


IO$_ST ARTSPNDL 

Start spindle 


IO$_UNLOAD 

Unload drive 
(required by all 
disk drivers) 


IO$_WRITECHECK 

Write check data 


IO$_WRITECHECKH 

Write check header 
and data 


IO$_WRITEHEAD 

Write header and 
data 


IO$_WRITEMARK 

Write tape mark 


IO$_WRITEPBLK 

Write physical 
block 


IO$_WRITETRACKD 

Write track data 

Logical I/O 

IO$_READLBLK 

Read logical block 


IO$_REWIND 

Rewind tape 


IO$_REWINDOFF 

Rewind and set 
offline 


IO$_SENSEMODE 

Sense device mode 


IO$_SETMODE 

Set mode 


IO$_SKIPFILE 

Skip files 


IO$_SKIPRECORD 

Skip records 


IO$_WRITELBLK 

Write logical block 


IO$_WRITEOF 

Write end of file 

Virtual I/O 

IO$_ACCESS 

Access file 


IO$_ACPCONTROL 

Miscellaneous ACP 
control 


IO$_CREATE 

Create file 


IO$_DE ACCESS 

Deaccess file 


IO$_DELETE 

Delete file 


IO$_MODIFY 

Modify file 


IOS-MOUNT 

Mount volume 
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Table 7-1 (Cont.) VAX/VMS l/O-Function Codes 


Function 


IO$_READPROMPT 

IO$_READVBLK 

IO$_WRITEVBLK 


Codes Defined 

Read terminal with 
prompt message 

Read virtual block 
Write virtual block 


7.3.2 Determining Those Functions That Are Buffered I/O 

The second entry in a function-decision table indicates those 

functions that are handled as buffered-I/O operations. In 

selecting the functions that are to be buffered, you should take 

the following information into consideration: 

• Direct I/O is intended only for devices whose I/O 
operations always complete quickly. For example, although 
terminal I/O is fast, users can prevent the I/O operation 
from completing by using CTRL/S to halt the operation 
indefinitely; therefore, terminal I/O operations are buffered 
I/O. 

• Use of direct I/O requires that the process pages containing 
the buffer be locked in memory. Locking pages in memory 
increases the overhead of swapping the process that contains 
the pages. 

• Use of buffered I/O requires that the data be moved from 
the system buffer to the user buffer. Moving data requires 
additional time. 

• Routines that manipulate data before delivering it to the 
user (for example, an interrupt-servicing routine for a 
terminal) cannot gain access to the data if direct I/O is used. 
Therefore, transfers that require data manipulation must be 
buffered I/O. 

• VAX/VMS handles the quotas differently for direct I/O and 
buffered I/O, as described in the Guide to VAX/VMS System 
Management and Daily Operations. 

• Generally, DMA devices use direct I/O, while programmed 
I/O devices use buffered I/O. 
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Section 7.3.4 provides an example of the functions handled as 
buffered I/O operations. 


7.3.3 FUNCTAB Macro 

The FUNCTAB macro creates the function-decision table for a 
driver. 

Format 

FUNCTAB [action],codes 

action 

The address of a routine to call during I/O preprocessing of 
the specified I/O-function code or codes. A routine is specified 
only for the third through last entries of the table. The list of 
valid I/O functions and the list of buffered-I/O functions have 
no associated routines. 

codes 

The list of I/O-function codes. The macro expansion prefixes 
each code specified with the string IO$_; for example, 
READVBLK expands to IO$_READVBLK. 


7.3.4 Example of FUNCTAB Macro Use 

In the example below, the routine (named XX_READ) called for 
a read function is a driver routine. It appears later in the driver 
module. The routines EXE$SETMODE and EXE$SENSEMODE, 
preceded by plus signs ( + ) in the macro argument, are 
VAX/VMS routines that preprocess I/O requests for the 
device's set-characteristics and sense-mode functions. 
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XX.FUNCTABLE: 

FUNCTAB 

<READLBLK,- 
READPBLK,- 
READVBLK,- 
SENSEMODE,- 
SENSECHAR,- 
SETMODE.- 
SETCHAR,- 

> 

FUNCTAB 

<READLBLK,- 
READPBLK,- 
READVBLK,- 
SENSEMODE,- 
SENSECHAR,- 
SETMODE,- 
SETCHAR,- 

> 

FUNCTAB XX_READ,- 

<READLBLK,- 
READPBLK,- 
READVBLK,- 

> 

FUNCTAB +EXESSETMODE,- 

<SETCHAR,- 
SETMODE,- 

> 

FUNCTAB +EXE$SENSEMODE,- 

<SENSECHAR,- 
SENSEMODE,- 

> 


Function-decision table 

Valid functions 

Read logical block 

Read physical block 

Read virtual block 

Sense reader mode 

Sense reader characteristics 

Set reader mode 

Set reader characteristics 

Buffered-I/O functions 
Read logical block 
Read physical block 
Read virtual block 
Sense reader mode 
Sense reader characteristics 
Set reader mode 
Set reader characteristics 

Read functions 

Read logical block 
Read physical block 
Read virtual block 

Set mode/characteristics 
Set reader characteristics 
Set reader mode 

Sense mode/characteristics 
Sense reader characteristics 
Sense reader mode 
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The Queue-I/O-Request system service uses the driver's 
function-decision table to determine which FDT routines to 
call. These FDT routines validate user-specified arguments in 
the I/O request. VAX/VMS contains many device-independent 
FDT routines. Device drivers contain device-dependent FDT 
routines. 

A driver should call the VAX/VMS device-independent FDT 
routines whenever possible. This practice encourages the use of 
well-debugged routines and minimizes driver size. 


8.1 Context for FDT Routine Execution 

The Queue-I/O-Request system service calls all FDT routines 

in the context of the process that requested the I/O operation. 

Characteristics of process context at the time of a call to an FDT 

routine are as follows: 

• Virtual addresses are mapped according to the process 
page tables. This mapping allows FDT routines access to 
user-specified virtual addresses. 

• The process is executing in kernel mode because the Queue- 
I/O-Request system service executes a Change-Mode-to- 
Kemel instruction. 

• The process privileges remain unchanged. 

• Interrupt priority level is set to IPL$_ASTDEL. Therefore, 

the process can be rescheduled but cannot receive ASTs. 
Paging can occur. 

• FDT routines cannot call system services or VAX RMS 
services. 
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8.2 Registers Preset for FDT Routine Execution 

The Queue-I/O-Request system service also sets up a series of 
registers for the FDT routines before calling them. Table 8-1 
lists the registers. 

Table 8-1 Registers Loaded by Queue-I/O-Request Service 

Register 

Content 

RO 

Address of the FDT routine being called 

R3 

Address of the l/O-request packet for the current I/O 
request 

R4 

Address of the process-control block (PCB) of the 
current process 

R5 

Address of the unit-control block of the device 
assigned to the user-specified process-1/0 channel 

R6 

Address of the channel-control block that describes 
the user-specified process-1/0 

R7 

Bit number of the user-specified l/O-function code 

R8 

Address of the current entry in the function-decision 
table 

AP 

Address of the first function-dependent parameter 
specified in the user's request 




8.3 Conventions Followed by FDT Routines 



Because FDT routines are called by the Queue-I/O-Request 
system service and return to it or, in turn, call another 
VAX/VMS routine, they must follow certain conventions to 
preserve register content and the expected process context. 



8-2 











Writing FDT Routines 


8.3.1 


8.3.2 


Register Conventions 

FDT routines are responsible for preserving the contents of R3 
through R8 across subroutine calls. FDT routines can use RO 
through R2 and R9 through Rll without saving their previous 
contents. If an FDT routine needs to use R3 through R8, the 
routine can use the push and pop register instructions to save 
registers on the stack and later restore them. The following is 
an example. 

PUSHR #~M<R3,R4,R5> ; Save R3-R5 on the stack 


POPR #~M<R3,R4,R5> ; Restore R3-R5 from the stack 


Process Context Conventions 

The Queue-I/O-Request system service executes in the context 
of the process that issues the I/O request, but in kernel mode 
and at IPL$_ASTDEL. The Queue-I/O-Request system service 
expects FDT routines to preserve this context. Therefore, an 
FDT routine observes the following conventions: 

• It does not lower IPL below IPL$_ASTDEL. 

• If a routine raises IPL, it must lower IPL to IPL$_ASTDEL 
before exiting. 

• It does not alter the stack without restoring its original state 
before exiting. 

• It must observe the register conventions described in the 
previous section. 

• It exits either by an RSB instruction to return control to the 
system service, or it issues a JMP instruction to one of the 
VAX/VMS routines described in Section 8.4. 
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8.4 Transferring Into and Out of an FDT Routine 

To transfer control to an FDT routine, the Queue-I/O-Request 
system service loads the address of the FDT routine into a 
register and executes a jump to subroutine instruction, as 
follows: 

JSB (RO) 

> 

Each FDT routine chooses an exit path on the basis of the 
following factors: 

• Whether another FDT routine needs to be called to perform 
additional function-specific processing 

• Whether an error is found in the I/O request 

• Whether the operation is complete 

• Whether the I/O operation requires and is ready for device 
activity 

The FDT routines, as illustrated in Figure 8-1, must transfer 
control out of the FDT processing loop and into a VAX/VMS 
routine that queues an I/O-request packet, completes an I/O 
request, or aborts an I/O request. The Queue-I/O-Request 
system service does not stop scanning the function-decision 
table. Therefore, you must ensure that all valid function codes 
in a driver's function-decision table eventually call an FDT 
routine that does not return control to the Queue-I/O-Request 
system service. 

An FDT routine can exit using any of the methods summarized 
in Table 8-2. The first method returns to the Queue-I/O- 
Request system service. All other methods jump to VAX/VMS 
routines that take the appropriate action. See Section 8.8 for 
detailed descriptions of these routines. 
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Figure 8-1 Queue-I/O-Request Scan of a Function-Decision 
Table 
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Table 8-2 


FDT Exit Methods 


Exit Method Result 

RSB Returns to the Queue-I/O-Request 

system service. The FDT routine 
returns to the system service 
because the routine knows that 
the function-decision table contains 
a subsequent entry with the same 
function-code bit set. As a result, 
the system service calls another 
FDT routine. 

JMP G~EXE$QIODRVPKT Transfers control to a VAX/VMS 

or routine that queues an I/O packet 

JSB G~EXE$ALTQUEPKT to a driver. The FDT routine 

uses this exit method if all 
preprocessing is complete, if 
no fatal errors are found in the 
specification of an I/O request, 
and if device activity is required to 
complete the I/O request. 

Once an FDT routine transfers 
control to either of these routines, 
no driver code that further 
processes the I/O request can 
refer to the process virtual address 
space. 

EXE$QIODRVPKT is the standard 
method used to queue an I/O 
request for device activity. This 
routine initiates driver action only 
if the device unit is currently 
idle, if no I/O request is being 
processed. If the device unit is 
busy, EXESQIODRVPKT queues 
the request to the unit so that the 
driver will process it when the unit 
becomes available. 

In contrast, EXE$ALTQUEPKT 
initiates driver action at a special 
driver entry point without regard 
for the device unit's activity status. 
This routine is called by drivers 
that can handle two or more I/O 
requests simultaneously. 
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Table 8-2 (Cont.) FDT Exit Methods 


Exit Method Result 

JMP G~EXE$FINISHIO Transfers control to a VAX/VMS 

routine that writes a quadword 
of final I/O status from RO and 
R1 into the I/O status field of the 

l/O-request packet (IRP$I_MEDIA 

and IRP$L_MEDIA+4). The routine 
then inserts the l/O-request packet 
in the I/O postprocessing queue. 

An FDT routine that discovers a 
device-dependent error should 
always return status using 
EXE$FINISHIO or EXE$FINISHIOC. 
The routine returns to the Queue- 
l/O-Request system service 
the two longwords of status 
contained in the l/O-status block 
(if any) specified in the Queue-I/O- 
Request. 

JMP G~EXE$FINISHIOC Transfers control to a routine that 

performs the same functions as 
EXE$FINISHIO except that this 
routine always clears the second 
longword of the final I/O status. 

JMP G^EXESABORTIO Transfers control to a VAX/VMS 

routine that aborts an I/O request. 
An FDT routine that discovers 
a device-independent error in an 
I/O request should always use 
this method of exit. The routine 
stores a longword of status in 
RO and returns this to the system 
service. Inability to gain access to 
a data buffer is an example of a 
device-independent error. 


8.5 FDT Routines for Direct I/O 

The VAX/VMS operating system provides two standard 
FDT routines that are applicable for direct I/O operations: 
EXE$READ and EXE$WRITE. 
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When called by the driver, these routines completely prepare a 
direct I/O read or write request. Thus, a driver that uses these 
routines eliminates the need for its own device-specific FDT 
routines. 

EXE$READ and EXE$WRITE are described in Section 8.7. 


8.6 FDT Routines for Buffered I/O 

Device drivers for buffered I/O operations must contain their 
own device-specific FDT routines. An FDT routine for buffered 
I/O must perform the following steps: 

1 Confirm either read or write access to the user's buffer 

2 Allocate a buffer in system space 


8.6.1 Checking the User's Buffer 

First the FDT routine calls EXE$READCHK or EXE$WRITECHK 
to confirm write or read access, respectively, to the user's 
buffer. Both of these routines write the transfer byte count 
into IRP$W_BCNT. EXE$READCHK also sets IRP$V_FUNC in 
IRP$W_STS to indicate that the function is a read. 


8.6.2 Allocating the System Buffer 

Next, the FDT routine allocates a system buffer. First, it adds 
12 bytes for a buffer header to the byte count passed in the P2 
parameter of the user's I/O request. This is the total system 
buffer size. The FDT routine then calls EXE$BUFFRQUOTA 
to ensure that the user has sufficient remaining resources. If 
EXE$BUFFRQUOTA returns with a success code, the FDT 
routine calls EXE$ALLOCBUF, which allocates the buffer and 
writes the buffer's size and type into its third longword. 

Once the buffer is allocated, the FDT routine takes the following 
steps: 

1 Loads the address of the system buffer into IRP$L_SVAPTE. 


2 Loads the total size of the system buffer into IRP$W_BOFF. 
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3 Subtracts the system buffer size from JIB$L_BYTCNT. A 
longword in the PCB (PCB$I^_JIB) points to the location of 
the job-information block (JIB). 

4 Stores the starting address of the system buffer data area in 
the first longword of the buffer header. 

5 Stores the user's buffer address in the second longword of 
the header. 

6 Copies data from the user buffer to the system buffer if the 
I/O request is a write operation. 

At this point, buffers are ready for the transfer. Figure 8-2 

illustrates the format of the system buffer. 

Figure 8-2 Format of System Buffer for Buffered I/O Read 
Operations 


SYSTEM BUFFER 
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8.6.3 


Appendix C provides additional information about 
EXE$READCHK, EXE$WRITECHK, EXE$BUFFRQUOTA, and 
EXE$ALLOCBUF. 


Completion of Buffered I/O in I/O Postprocessing 

When the transfer finishes, the driver returns control to 
VAX/VMS for completion of the I/O request. The driver 
writes the final count of bytes transferred into the high-order 
word of RO and the final request status in the low order words 
of RO and Rl. The driver must leave the buffer header intact; 
I/O postprocessing relies on the header's accuracy. When 
VAX/VMS I/O postprocessing gains control, it performs three 
steps: 

1 Adds the value in IRP$W_BOFF to JIB$L_BYTCNT to 
update the user's byte count quota 

2 If IRP$L_SVAPTE is nonzero, assumes a system buffer was 
allocated and checks to see whether IRP$V_FUNC is set in 
IRP$W_STS 

3 If IRP$V__FUNC is clear, deallocates the system buffer 
used for the write operation; if IRP$V_FUNC is set, the 
kernel-mode AST copies the data to the user's buffer and 
then deallocates the buffer in addition to performing other 
kernel-mode AST functions 

The kernel-mode AST performs the following steps to complete 
a buffered read operation: 

1 Obtains the address of the system buffer from IRP$L_ 
SVAPTE 

2 Obtains the number of bytes to write to the user's buffer 
from IRP$W_BCNT (for a read operation) 

3 Obtains the address of the user's buffer from the second 
longword of the system buffer header 

4 Checks for write accessibility on all pages of the user's 
buffer (for a read operation) 

5 Copies the data from the system buffer to the process's 
buffer (for a read operation) 
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6 Deallocates the system buffer. Note that the system uses the 
size listed in the buffer's header to deallocate the buffer. 


8.7 FDT Routines Provided by VAX/VMS 

The VAX/VMS FDT routines perform I/O request validation 
that is common to many devices. Whenever possible, drivers 
should take advantage of these routines. Normally, if a 
VAX/VMS FDT routine is called, no additional FDT processing 
is required. All of the VAX/VMS FDT routines described here 
exit by transferring control to one of the following VAX/VMS 
routines: 

• EXE$QIODRVPKT 

• EXE$FINISHIO 

• EXE$FINISHIOC 

• EXE$ABORTIO 

Once a VAX/VMS FDT routine is called, no subsequent FDT 
processing occurs. 

For information about additional FDT routines, see Appendix C. 


8.7.1 EXE$ONEPARM 

EXE$ONEPARM processes an I/O-function code that has one 
parameter associated with it. 

Exit Method 

Queues the I/O-request packet to the driver. 

Description 

Processes an I/O-function code that requires only one 
parameter that needs no checking; for example, the parameter 
does not have to be checked for read or write accessibility. 
EXE$ONEPARM stores the parameter, found at 0(AP), in 
IRP$D_MEDIA of the I/O-request packet. Then, it queues the 
I/O-request packet to the driver. 
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8.7.2 


EXESREAD 

EXE$READ processes a logical-read or physical-read function 
for a direct I/O operation. EXE$READ cannot be used for 
buffered I/O operations. 

Exit Method 

Aborts the I/O request if an error occurs, or dismisses and 
resubmits the I/O request if the user I/O buffers cannot be 
locked in memory; otherwise, queues the I/O-request packet to 
a driver. 

Description 

Sets the I/O-function bit in the status field (IRP$V_FUNC in 
IRP$W_STS) of the I/O-request packet. This bit indicates that 
the function is a read. 

EXE$READ writes the fourth parameter, located at 12(AP) into 
the carriage-control field (IRP$B_CARCON). 

The routine replaces the logical-function code IO$_READLBLK 
with the physical-function code IO$_READPBLK in the 
function-code field (IRP$W_FUNC) of the I/O-request packet. 

If the second parameter (the transfer byte count) is zero, 
EXE$READ queues the I/O-request packet to a device driver. 
The second parameter is found at 4(AP). If the byte count is 
not zero, EXE$READ uses the starting address of the transfer, 
found at 0(AP), and the transfer byte count as arguments to the 
routine EXE$READLOCK. 

The routine EXE$READLOCK calls EXE$READLOCKR, which 
immediately calls EXE$READCHKR. This last subroutine 
determines whether the caller's buffer permits write access. 

If EXE$READCHKR finds that the buffer is accessible, it updates 
the I/O-request packet by writing the size in bytes of the 
transfer to IRP$W_BCNT and setting the read status bit in 
IRP$W_STS (IRP$V_FUNC). The maximum number of bytes 
that EXE$READ can transfer is 65,535 (128 pages minus one 
byte). 
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If the buffer does not allow write access, EXE$READCHKR 
returns access violation status to its caller, EXE$READLOCKR, 
which summons its caller (EXE$READLOCK) as a coroutine. 

When EXE$READLOCK is called as a coroutine, it does 
not take any error action. Instead, it passes control to 
EXE$READLOCKR, which aborts the queue-I/O request 
with access violation status. EXE$READLOCK is called 
as a coroutine for the convenience of drivers that call 
EXE$READLOCKR directly. (See Appendix C for more details.) 

After EXE$READCHKR confirms the buffer's write accessibility, 
EXE$READLOCKR calls the routine MMG$IOLOCK to 
lock into memory those pages that contain the buffer. 
MMG$IOLOCK, can return success, page fault, or error status 
to EXE$READLOCKR. 

If MMG$IOLOCK succeeds, EXE$READLOCKR stores 
the address of the process page-table entry (PTE) in 
the field IRP$L_SVAPTE and returns success status to 
EXE$READLOCK. 

However, if MMG$IOLOCK reports a page fault, 
EXE$READLOCKR adjusts direct I/O count and AST count 
to the values they held before the I/O request, deallocates the 
I/O-request packet and restarts the request procedure at the 
Queue-I/O-Request system service. This procedure is carried 
out so that the user process can receive asynchronous system 
traps while it waits for the page fault to complete. Once the 
page is faulted into memory, the system service will resubmit 
the queue-I/O request. 

MMG$IOLOCK can report either of two errors: access violation 
(SS$_ACCVIO) and insufficient working set limit (SS$_ 
INSFWSL). When EXE$READLOCKR receives an error, it 
aborts the request with error status. 

After EXE$READLOCK returns to EXE$READ, the routine 
passes control to the exit routine EXE$QIODRVPKT so that the 
request is queued to the driver. 
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8.7.3 


8.7.4 


EXE$SENSEMODE 

EXE$SENSEMODE processes the sense-device-mode and 
sense-device-characteristics functions by reading fields of the 
unit-control block. No device activity occurs. 

Exit Method 

Transfers control to EXE$FINISHIO. 

Description 

Loads the device-dependent characteristics field (UCB$L_ 
DEVDEPEND) of the unit-control block into Rl. 
EXE$SENSEMODE then loads a normal completion status 
(SS$_NORMAL) into RO. Finally, it transfers control to 
EXE$FINISHIO to insert the I/O-request packet in the I/O 
postprocessing queue. 


EXE$SETCHAR 

EXE$SETCHAR processes the set-device-mode and set-device- 
characteristics functions. If setting device characteristics requires 
no device activity or requires no synchronization with fork 
processing, the driver's FDT entry can specify EXE$SETCFIAR; 
otherwise, it must specify EXE$SETMODE. 

Exit Method 

Aborts the I/O request on error; otherwise, transfers control to 
EXE$FINISHIO. 

Description 

Determines whether the process has read access to the 
quadword that describes the new characteristics for the device. 
The first parameter, found at 0(AP), specifies the address of 
the quadword. If the process does not have read access to the 
quadword, EXE$SETCHAR aborts the request. 

If the process has read access, EXE$SETCHAR stores the new 
characteristics in fields of the device's unit-control block. If the 
function is IO$_SETCHAR, the device type and class fields 
(UCB$B_DEVCLASS and UCB$B_DEVTYPE, respectively) of 
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8.7.5 


the unit-control block receive the first word of data addressed 
by the parameter. 

For both the IO$_SETCHAR and IO$_SETMODE functions, 
the routine writes the second word of data into the UCB'S 
default-buffer-size field (UCB$W_DEVBUFSIZ) and the 
third and fourth words of data into the device-dependent- 
characteristics field (UCB$L_DEVDEPEND). 

Finally, EXE$SETCHAR stores the normal completion status 
(SS$_NORMAL) in RO and transfers control to EXE$FINISHIO 
to insert the I/O-request packet in the I/O postprocessing 
queue. 


EXE$SETMODE 

EXE$SETMODE processes the set-device-mode and set-device¬ 
characteristics functions by activating the device. 

Exit Method 

Aborts the I/O request if an error occurs; otherwise, queues the 
I/O-request packet to the device driver. 

Description 

Determines whether the process has read access to the 
quadword that describes the new characteristics for the device. 
The first parameter, found at 0(AP), specifies the address of 
the quadword. If the process does not have read access to the 
quadword, EXE$SETMODE aborts the request. 

If the process has read access, EXE$SETMODE stores the 
new characteristics in the media field (IRP$L_MEDIA and 
IRP$L_MEDIA+4) of the I/O-request packet. The routine then 
transfers control to the exit routine EXE$QIODRVPKT, which 
queues the request to the appropriate device driver. 
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8.7.6 


EXESWRITE 

EXESWRITE processes a logical- or physical-write function for a 
direct I/O operation. EXE$WRITE cannot be used for buffered 
I/O operations. 

Exit Method 

Aborts the I/O request if an error occurs, or dismisses the I/O 
request if the user I/O buffers cannot be locked in memory; 
otherwise, queues the I/O-request packet to a driver. 

Description 

Writes the fourth parameter, found at 12(AP) into the I/O- 
request packet's carriage control field (IRP$B_CARCON). 


EXE$WRITE replaces the logical-function code IO$_ 
WRITELBLK with the physical-function code IO$_WRITEPBLK 
in the function-code field of the I/O-request packet 
(IRP$W_FUNC). 

If the second parameter (the transfer byte count) is zero, 

EXE$WRITE queues the I/O-request packet to the driver. 

The second parameter is found at 4(AP). If the byte count is 
not zero, EXE$WRITE uses the starting address of the transfer, 
found at 0(AP), and the transfer byte count as arguments to the 
routine EXE$WRITELOCK. 

The routine EXE$WRITELOCK calls EXE$WRITELOCKR, which 
immediately calls EXE$WRITECHKR. This last subroutine 
determines whether the caller's buffer permits read access. 

If EXE$WRITECHKR finds that the buffer is accessible, it 
updates the I/O-request packet by writing the size in bytes 
of the transfer to IRP$W_BCNT. EXE$WRITE can transfer a 
maximum of 65,535 bytes (128 pages minus one byte). 

If the buffer does not allow read access, EXE$WRITECHKR 
returns access violation status to its caller, EXE$WRITELOCKR, 
which summons its caller (EXE$WRITELOCK) as a coroutine. 
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When EXE$WRITELOCK is called as a coroutine, it does 
not take any error action. Instead, it passes control to 
EXE$WRITELOCKR, which aborts the queue-I/O request 
with access violation status. EXE$WRITELOCK is called 
as a coroutine for the convenience of drivers that call 
EXE$WRITELOCKR directly. (See Appendix C for more 
details.) 

After EXE$WRITECHKR confirms the buffer's read accessibility, 
EXE$WRITELOCKR calls the routine MMG$IOLOCK to 
lock into memory those pages that contain the buffer. 
MMG$IOLOCK can return success, page fault, or error status to 
EXE$WRITELOCKR. 

If MMG$IOLOCK succeeds, EXE$WRITELOCKR stores the 
address of the process page-table entry (PTE) in IRP$I^_ 
SVAPTE and returns success status to EXE$WRITELOCK. 

However, if MMG$IOLOCK reports a page fault, 
EXE$WRITELOCKR adjusts direct I/O count and AST count to 
the values they held before the I/O-request packet and restarts 
the request procedure at the Queue-I/O system service. The 
routine carries out this procedure so that the user process can 
receive ASTs while it waits for the page fault to complete. 
Once the page is faulted into memory, the system service will 
resubmit the queue-I/O request. 

MMG$IOLOCK can report either of two errors: access violation 
(SS$_ACCVIO) and insufficient working set limit (SS$_ 
INSFWSL). When EXE$WRITELOCKR receives an error, it 
aborts the request with error status. 

After EXE$WRITELOCK returns to EXE$WRITE, the routine 
passes control to the exit routine EXE$QIODRVPKT so that the 
request is queued to the driver. 


EXESZEROPARM 

EXESZEROPARM processes an I/O-function code that has no 
associated parameters. 

Exit Method 

Queues the I/O-request packet to the driver. 
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Description 

Processes an I/O-function code that describes an I/O operation 
completely without any additional function-specific parameters. 
The only FDT processing necessary for a zero-parameter- 
function code is to zero-fill the field of the I/O-request packet 
that normally contains a user-specified parameter (IRP$L__ 
MEDIA). Then EXE$ZEROPARM queues the I/O-request 
packet to a device driver. 


8.8 Exit Routines in the VAX/VMS System 

Ultimately, FDT processing must terminate by transferring 
control to one of the following VAX/VMS routines: 
EXE$ABORTIO, EXE$FINISHIO, EXE$FINISHIOC, 
EXE$ALTQUEPKT, or EXE$QIODRVPKT. Each of these 
routines returns the system service status code to the user. 


8.8.1 EXE$ABORTIO 

When an FDT routine determines that an I/O request cannot 
be completed because of an error in the specification of the 
request or in FDT processing, the FDT routine transfers control 
to the VAX/VMS routine EXE$ABORTIO to abort the request. 
EXE$ABORTIO gains control without any change in the process 
context. Interrupt priority level is at IPL$_ASTDEL; the process 
virtual space is mapped; and the process is executing in kernel 
mode. 

Required Register Contents 

RO Queue-I/O-Request system service final status code 

R3 Address of the current I/O-request packet 

R4 Address of the process-control block of the current process 

R5 Address of the unit-control block of the device unit assigned 
to the process-l/O channel 

R3 through R5 always contain the I/O-request packet, PCB, 
and UCB addresses at the entry to an FDT routine. The FDT 
routine should be careful not to destroy these values. 


8-18 






Writing FDT Routines 


8 . 8.2 


Description 

EXE$ABORTIO clears the address of the I/O-status block in 
the I/O-request packet (IRP$L_JOSB) so that no status will 
be returned during I/O postprocessing. EXE$ABORTIO also 
clears the bit in the I/O-request packet (ACB$V_QUOTA in 
the field IRP$B_RMOD). When set, this bit indicates that the 
requesting process specified an AST routine. If necessary, the 
routine readjusts the process's use of its AST quota. 

Then EXE$ABORTIO inserts the I/O-request packet in the I/O 
postprocessing queue. If no other entries are in the queue, 
EXE$ABORTIO requests a software interrupt at IPL$_IOPOST. 
This interrupt causes postprocessing to occur before any other 
instructions in the EXE$ABORTIO routine are executed. 

When all I/O postprocessing has been completed, 
EXE$ABORTIO regains control and finishes the I/O operation 
as follows: 

• Lowers IPL to zero, which is the normal IPL for a process 
user 

• Changes mode back to the original processor access mode 

• Returns from the system service to the code of the image 
that originally requested the I/O operation. EXE$ABORTIO 
returns RO, which contains the final status code saved when 
the exit routine was called, to its caller. 

As a result of this exit method, any ASTs specified when the 
I/O request was issued will not be delivered, and any event 
flags requested will not be set. 


EXE$FINISHIO and EXE$FINISHIOC 

Many I/O requests need no device activity to be completed. 
The FDT routine(s) can complete the entire I/O request and 
immediately return status concerning the operation to the 
process. However, the VAX/VMS operating system provides 
two VAX/VMS I/O completion routines: EXE$FINISHIO and 
EXE$FINISHIOC. EXE$FINISHIO returns a quadword of I/O 
status. EXE$FINISHIOC returns a quadword of I/O status with 
the second longword containing zero. 
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These routines gain control without any change in process 
context. Interrupt priority level is at IPL$_ASTDEL; the process 
page-tables are mapped; and the process is executing in kernel 
mode. 

Required Register Contents 

RO Value to be placed in the first longword of final I/O status 
when the Queue-I/O-Request system service returns final 
status 

R1 Value to be placed in the second longword of final I/O status 
(EXESFINISHIO only) 

R3 Address of the current l/O-request packet 

R4 Address of the process-control block of the current process 

R5 Address of the unit-control block of the device unit assigned 

to the process-l/O channel 

R3 through R5 always contain the I/O-request packet, PCB, 
and UCB addresses at the entry to an FDT routine. The FDT 
routine should be careful not to destroy these values. 

Description 

EXESFINISHIO and EXE$FINISHIOC modify fields in the I/O 
database and then complete the I/O request in the following 
steps: 

1 Increase the number of I/O operations completed on the 
current device in the operation count field of the unit-control 
block (UCB$L_OPCNT) 

2 Store the contents of RO and R1 in the media fields of the 
I/O-request packet (IRP$L_MEDIA and IRP$L_MEDIA+4) 

3 Insert the I/O-request packet in the I/O postprocessing 
queue and, if the queue is empty, request a software 
interrupt at IPL$_IOPOST 

EXESFINISHIO and EXESFINISHIOC lose control to I/O 
postprocessing because postprocessing executes at the 
higher IPL of IPL$_IOPOST. When EXESFINISHIO and 
EXESFINISHIOC regain control, they complete processing 
in three steps: 

1 Lower IPL to zero, which is the normal IPL for a process. 
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2 Change mode back to the original processor access mode. 

3 Return from the system service to the image that originally 
requested the I/O operation. The image receives status 
SS$_NORMAL in RO, indicating that the queue-I/O request 
has completed without device-independent error. 


8.8.3 




EXESQIODRVPKT 

Some I/O functions require device activity, or at least access 
to device registers, for the I/O operation to be completed. 
Common examples are read and write functions. While 
FDT routines can perform extensive preprocessing, such 
as determining whether user buffers are accessible and 
reformatting data into buffers in the system address space, 
they should not access device registers because the device 
might be active. 

Furthermore, FDT routines should exercise restraint when 
modifying the unit-control block. Routines usually access the 
UCB at driver fork IPL to synchronize modifications, and FDT 
routines do not execute at this interrupt priority level. Drivers 
containing FDT routines that access device registers or carelessly 
modify the unit-control block risk unpredictable operation or a 
system failure. 

For this type of I/O function, the associated FDT routines 
perform all preprocessing and then transfer control to the 
VAX/VMS routine EXE$QIODRVPKT. It queues the I/O- 
request packet to a device driver and attempts to transfer 
control to the device driver's start-I/O routine. If the device 
unit is busy, EXESQIODRVPKT inserts the I/O-request packet 
in a priority-ordered queue of packets waiting for the unit. 

Required Register Contents 

R3 Address of the l/O-request packet 

R4 Address of the process-control block of the current process 

R5 Address of the unit-control block for the device unit assigned 
to the process-l/O channel 

Description 

EXE$QIODRVPKT calls EXE$INSIOQ, which first raises the 
interrupt priority level of the process to the fork level of the 
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driver (UCB$B_FIPL). Driver fork level is, by convention, the 
interrupt priority level at which device drivers and VAX/VMS 
read and alter critical portions of the device's unit-control block. 
By executing at fork level, EXE$INSIOQ ensures that, while it is 
running, a driver fork process for the device unit cannot also be 
running. 

EXE$INSIOQ tests the UCB status word to see if the unit is 
busy. 

If the device unit is not busy, EXE$INSIOQ calls the VAX/VMS 
routine IOC$INITIATE to create a fork process context in which 
the driver can process the I/O request. IOC$INITIATE creates 
this context and activates the driver in the following steps: 

1 Sets the busy bit of the device's unit-control block (UCB$V_ 
BSY in UCB$L_STS) 

2 Stores the address of the current I/O-request packet in the 
UCB field UCB$L_IRP 

3 Copies the transfer parameters contained in the I/O-request 
packet into the unit-control block: 

• Copies the starting address from IRP$L_SVAPTE to 
UCB$L_SVAPTE 

• Copies the byte offset within the page from IRP$W_ 
BOFF to UCB$W_BOFF 

• Copies the low order word of the byte count from 
IRP$W_BCNT to UCB$W_BCNT 

4 Clears the cancel-I/O and timeout bits in the UCB 
status word (UCB$V_CANCEL and UCB$V_TIMOUT 
in UCB$W_STS) 

5 If the I/O request specifies a diagnostic buffer, as indicated 
by the bit IRP$V_DIAGBUF in IRP$W_STS, stores the 
system time in the buffer to which IRP$L_DIAGBUF points 
(the Queue-I/O-Request system service having already 
allocated the buffer) 

6 Finds the entry point of the device driver's start-I/O routine 
using the following chain of pointers: 

UCB --> DDT —> start-I/O entry point 

> 

8-22 




Writing FDT Routines 


7 Transfers control to the driver start-I/O routine using a JMP 
instruction 

If, on the other hand, EXE$INSIOQ finds that the device 
is busy, it inserts the I/O-request packet in the device 
unit's pending-I/O queue for processing later by calling 
EXE$INESRTIRP. The pending-I/O queue is ordered by two 
factors: 

• The time that the entry is queued; for each IPL, the queue is 
ordered on a first-in/first-out basis 

• The priority of the I/O-request packet, which is derived 
from the requesting process's base priority and stored in the 
field IRP$B_PRI 

After completing one of the operations described above, 
EXE$INSIOQ reduces the interrupt priority level to 
IPL$__ASTDEL, the level at which it began executing. 
EXE$INSIOQ returns control to EXE$QIODRVPKT. Finally, 
EXE$QIODRVPKT returns from the Queue-I/O-Request system 
service in the following steps: 

1 Loads a success status code (SS$_NORMAL) into RO 

2 Reduces the interrupt priority level to 0 

3 Changes mode to the access mode of the requesting process 
at the time of the I/O request by issuing an REI instruction 

4 Returns from the system service call 

The system sets and clears the busy bit in the UCB status 
word for the device unit. This bit prevents the driver from 
being called to service a device unit that is already engaged in 
another I/O request. 

When a device driver's start-I/O routine gains control, the 
process that queued the I/O request might no longer be the 
mapped process. Therefore, the driver must assume that all 
information regarding the I/O request is in the unit-control 
block or the I/O-request packet and that all buffer addresses in 
the unit-control block are either system addresses or page-frame 
numbers that can be interpreted in any process context. 
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8.8.4 


For direct I/O operations, FDT routines also must have locked 
all user buffer pages in physical memory because paging cannot 
occur at driver fork level or higher interrupt priority levels. The 
process virtual address space is not guaranteed to be mapped 
again until VAX/VMS delivers a kernel-mode AST to the 
requesting process as part of I/O postprocessing. 


EXE$ALTQUEPKT 

You might want special-purpose drivers to use their own 
internal I/O queues as well as the device unit's I/O queue 
(UCB$L_IOQFL) provided by VAX/VMS. These internal 
queues allow the driver to handle I/O requests even if the 
device is busy with another I/O operation. 

EXE$ALTQUEPKT permits the driver to ignore synchronization 
of the I/O queue for the unit. When called by an FDT routine, 
EXE$ALTQUEPKT gains access to the driver at the alternate 
start-I/O entry point specified in the driver-dispatch table 
(offset DDT$L_ALTSTART). This entry point bypasses the unit 
I/O queue and the device busy flag; thus, the driver is activated 
regardless of whether the device unit is busy. 

A driver that uses EXE$ALTQUEPKT must not only maintain 
its internal queues but must also synchronize those queues 
with the unit's pending-I/O queue, which the operating system 
maintains. 

Drivers complete I/O requests by calling the routine 
COM$POST. This routine places each I/O-request packet 
in a postprocessing queue and returns control to the driver. The 
driver can then fetch another packet from an internal queue. 
For more information about COM$POST, see Appendix C. 

If a driver processes more than one I/O-request packet at the 
same time, separate fork blocks must be used. 

Be aware that programming a device driver to process 
simultaneous I/O requests requires detailed knowledge of 
VAX/VMS internal design. 
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Required Register Contents 

R3 Address of the 1/0-request packet 
R5 Address of the unit-control block 

You must assume that the contents of RO through R5 are 
destroyed upon return to the FDT routine. 

Description 

EXE$ALTQUEPKT performs the following steps: 

1 Saves the current interrupt priority level on the stack 

2 Raises interrupt priority level to driver fork level 
(UCB$B_FIPL) 

3 Finds the entry point of the alternate start-I/O routine using 
the following chain of pointers: 

UCB —> DDT —> alternate start-I/O address 

4 Calls the driver at alternate start-I/O address 

When the alternate start-I/O routine finishes, it returns 
control to EXE$ALTQUEPKT by executing an RSB instruction. 
Unlike the other FDT exit routines, EXE$ALTQUEPKT is 
called with a JSB instruction rather than a JMP instruction. 
EXE$ALTQUEPKT restores interrupt priority level to that 
which existed when it was called, then returns control to 
the FDT routine that called it. The FDT routine performs 
any postprocessing and transfers control to the routine 
EXE$QIORETURN. 

When EXE$QIORETURN gains control, it performs the 
following steps: 

1 Sets the success status code SS$_NORMAL in RO 

2 Lowers the interrupt priority level to zero 

3 Returns (with the RET instruction) to the system-service 
dispatcher 


8-25 









9 


Writing the Start-1 /O Routine 


A driver start-I/O routine activates a device and then waits for 
a device interrupt or timeout. This chapter describes the start- 
I/O routine. Chapter 12 describes the reactivation of the driver 
routine that performs device-dependent I/O postprocessing. 
With a few exceptions, the start-I/O routine discussed in the 
following sections describes a DMA transfer using a single-unit 
controller. 


9.1 Transferring Control to Start-I/O 

The start-I/O routine of a device driver gains control from 
either of two VAX/VMS routines: EXE$QIODRVPKT or 
IOC$REQCOM. 

When FDT processing is complete for an I/O-request packet, 
the FDT routine transfers control to EXE$QIODRVPKT. If the 
designated device is idle, IOC$INITIATE is called to create 
a driver fork process. (This procedure is detailed in Section 
8.8.3.) The driver fork process then gains control in the start- 
I/O routine of the appropriate driver. If the device is busy, 
EXE$QIODRVPKT calls EXE$INSIOQ, which queues the packet 
to the device unit's pending-I/O queue. 

After a device completes an I/O operation, the driver fork 
process exits by transferring control to IOC$REQCOM. 
IOC$REQCOM inserts the I/O-request packet for the finished 
transfer into the postprocessing queue. It then dequeues the 
next I/O-request packet from the device unit's pending-I/O 
queue and calls IOC$INITIATE to create a new driver fork 
process that gains control at the entry point of the driver's 
start-I/O routine. 
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9.2 Context of a Driver Fork Process 

A start-I/O routine does not run in the context of a user 
process. Rather, it has the following context: 

Only system page-tables are mapped. 
Therefore, driver code cannot refer to 
virtual addresses in process address space. 

Execution occurs in the most privileged 
access mode and can, therefore, change 
IPL. 

The VAX/VMS routine that creates a driver 
fork process raises IPL to driver fork level 
before activating the driver. The driver can 
raise and lower IPL between driver fork 
level and IPL$_POWER. 

Execution occurs on the kernel or interrupt 
stack. The driver must not alter the 
state of the stack without restoring 
the stack to its previous state before 
relinquishing control. The stack used 
depends on whether the I/O startup is the 
result of a new I/O request or because 
a previously requested I/O operation has 
been completed. The choice of stacks 
must not affect the operation of the 
start-I/O routine. 

In addition to the context described, the VAX/VMS packet¬ 
queuing routines set up R3 and R5 for a driver start-I/O 
routine, as follows: 

• R3 contains the address of the I/O-request packet. 

• R5 contains the address of the unit-control block for the 
device. 

All registers must be preserved except for RO, Rl, R2, and R4. 

Before the packet-queuing routines call the start-I/O routine, 
they copy the following I/O-request packet fields into their 
corresponding slots in the device's unit-control block: 


IRP$W_BCNT 

-> 

UCB$W_BCNT 

IRP$W_BOFF 

-> 

UCB$W_BOFF 

IRP$L_SVAPTE 

-> 

UCB$l_SVAPTE 


System mapping 

Kernel mode 

High IPL 

Kernel or 
interrupt stack 
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9.3 Activating the Device 

The processing performed by a start-I/O routine is device 
specific. A start-I/O routine normally contains elements that 
perform the following functions: 

• Analyze the I/O function 

• Transfer the details of a transfer from the I/O-request packet 
into the unit-control block 

• Obtain and initialize the controller and, for DMA transfers, 
UNIBUS adapter resources 

• Modify device registers to activate the device 

The start-I/O routine elements listed above execute a series of 
steps to activate the device. The sections that follow describe 
those steps as performed for a sample DMA device such as 
a parallel communications link; the details of processing, 
however, are specific to the particular device. UNIBUS-related 
details of DMA transfers are described in Chapter 10. 


9.3.1 Obtaining Controller Access 

If the device is one of several attached to a controller, the 
start-I/O routine invokes the VAX/VMS macro REQPCHAN 
to assign the controller's data channel to the device unit. 
Controllers that control only one device do not require 
arbitration for the controller's data channel. REQPCHAN 
calls the VAX/VMS routine IOC$REQPCHANL that acquires 
ownership of the controller data channel. 

The transfer being controlled by the start-I/O routine discussed 
here requires no seek preceding the transfer. Disk I/O is an 
example of a transfer that requires a seek first. To permit seeks 
to be overlapped with transfers, invoke REQPCHAN with the 
argument PRI=HIGH. Specifying PRI=HIGH inserts a request 
for a channel at the head of the channel-wait queue. 

If the channel is not available, IOC$REQPCHANL suspends 
driver processing by saving the driver's context in the UCB fork 
block and inserting the fork block address in the channel-wait 
queue. IOC$REQPCHANL then returns control to the caller of 
the driver, that is, to IOC$INSIOQ, as illustrated in Figure 9-1. 
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The UCB fork block now represents the entire context of the 
suspended driver: 

• Saved R3 containing the address of the I/O-request packet 

• Implicitly saved R5 containing the UCB address 

• A return address in the driver 

IOC$REQPCHANL does not save R4 because it writes R4 
before returning control to the driver. 

Figure 9-1 UCB Insertion into Channel-Wait Queue 



ZK-928-82 


If the channel is available, IOC$REQPCHANL locates the 
interrupt-dispatch block for the channel with a pointer in the 
unit-control block: 

UCB --> CRB --> IDB 

The interrupt-dispatch block contains the address of the 
control/status register for the channel (IDB$L_CSR). 
IOC$REQPCHANL returns the control/status register address 
in R4. The driver for a unit attached to a dedicated controller 
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9.3.2 


must contain the code needed to load the control/status address 
into R4. 

IOC$REQPCHANL also writes the address of the new channel- 
owner's UCB in the owner field of the interrupt-dispatch block 
(IDB$L_OWNER). The driver's interrupt-servicing routine later 
reads this IDB field to determine which device unit owns the 
controller's data channel. A driver for a single-unit controller 
must fill the IDB$I^OWNER field in its controller-initialization 
or unit-initialization routines. 

The driver must maintain the stack in a known and consistent 
state for the resource-wait-queue mechanism to work. When 
IOC$REQPCHANL gains control, the top two items on the 
stack must be two return addresses: 

• 0(SP)—Address of the next instruction to be executed in the 
driver fork process 

• 4(SP)—Address of the next instruction to be executed in the 
routine that called the driver start-I/O routine 


Getting the l/O-Function Code and Converting the 
Code and Modifiers 

The start-I/O routine extracts the I/O-function code and 
function modifiers from the field IRP$W_FUNC and translates 
them into device-specific function-codes, which it loads into 
the device's control/status register or other control registers. 
The start-I/O routine described in this chapter creates and 
modifies a bit-mask that is to be loaded into the control/status 
register when the driver starts the device. To accomplish this, 
the start-I/O routine converts the function modifiers contained 
in IRP$W_FUNC into device-specific bit settings in the general 
register. 

At this point, the device driver follows procedures to obtain 
UNIBUS resources. These procedures are detailed in Chapter 
10 . 
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9.3.3 Computing the Transfer Length 

Because the device driven by this particular driver expects the 
transfer as a word count, the start-I/O routine computes the 
length of the transfer in words by dividing the byte count field 
of the unit-control block (UCB$W_BCNT) by 2. The routine 
loads the computed value into the device's word-count register. 
One of the FDT routines that processes the I/O request must 
ensure that the byte count for the transfer is even. An odd byte 
count results in the user's not receiving the last byte of data. 


9.3.4 Computing the Transfer's Starting Address 

The start-I/O routine calculates the address of the transfer using 
the byte offset field of the unit-control block (UCB$W_BOFF) 
and the number of the starting mapping register (CRB$L_ 
INTD+VEC$W_MAPREG). The result is an 18-bit value 
representing an address in UNIBUS address space. Section 
10.4 details the calculation of the starting address for a UNIBUS 
transfer. 

The start-I/O routine stores the low-order 16 bits of the 
computed UNIBUS address in the device's buffer-address 
register. It stores the two high-order bits of the computed 
UNIBUS address in the memory-extension bits of the register 
that contains the bit-mask described in Section 9.3.2. This 
register now contains the information on the device function 
that is to be placed in the device's control/status register and 
the two high-order bits of the UNIBUS address. 


9.3.5 Preparing the Device Activation Bit-Mask 

The start-I/O routine prepares the device-activation bit-mask 
by setting the interrupt-enable bit and the go bit in the general 
register that also contains the high-order bits of the UNIBUS 
address and the device-function bits. At this point the general 
register contains a complete command for starting the transfer, 
also known as the control mask. 

When the start-I/O routine copies the contents of the register 
into the device's control/status register, the device starts the 
transfer. Before activating the device, however, the start-I/O 
routine should perform the steps described in Sections 9.3.6 
and 9.3.7. 
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9.3.6 Blocking All Interrupts 

The start-I/O routine invokes the VAX/VMS macro DSBINT to 
block all interrupts. DSBINT raises IPL to IPL$_POWER and 
saves the previous IPL setting on the top of the stack. 


9.3.7 Checking for Power Failure 

The start-I/O routine examines the powerfail bits in the UCB's 
status word (UCB$V_POWER in UCB$L_STS) to determine 
whether a power failure has occurred since the start-I/O 
routine gained control. If the bit is not set, the transfer can 
proceed. 

If the bit is set, a power failure might have occurred between 
the time that the start-I/O routine wrote the first device register 
and the time that the start-I/O routine is ready to activate the 
device. Such a power failure could modify the already-written 
device registers and cause unpredictable device behavior if the 
device were to be started. 

If the bit UCB$V__POWER is set, the start-I/O routine branches 
to an error handler in the driver. The driver must clear 
UCB$V_POWER before error-recovery procedures can be 
started. Many drivers clear this field and transfer control to the 
beginning of the start-I/O routine, which restarts the processing 
of the I/O request. 


9.3.8 Activating the Device 

If no power failure has occurred, the start-I/O routine copies 
the contents of the control mask into the device control/status 
register. When the device notices the new contents of the 
device register, it begins to transfer the requested data. 
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9.4 Waiting for an Interrupt or Timeout 

Once the start-I/O routine activates the device, the driver fork 
process cannot proceed until one of these events occurs: 

• The device generates a hardware interrupt. 

• The device does not generate a hardware interrupt within 
an expected time limit, which is to say that a device timeout 
occurs. 

Still executing at IPL$_POWER, the driver's start-I/O routine 
asks VAX/VMS to suspend the driver fork process by invoking 
one of the following VAX/VMS macros: 

WFIKPCH Wait for an interrupt or timeout and keep the 

controller data channel 

WFIRLCH Wait for an interrupt or timeout and release the 

controller data channel 

Both of these macros invoke routines that return IPL to the 
previous level when they exit. These routines expect to find the 
return IPL on the stack. This IPL is saved on the stack by the 
DSBINT macro as described in Section 9.3.6. 

Drivers generally keep the controller data channel while waiting 
for the interrupt or timeout. Drivers of devices with dedicated 
controllers always keep the channel because only one unit ever 
needs it. For devices that share a controllers, some operations, 
such as disk seeks, do not require the controller once the 
operation has begun. In such cases, the driver can release 
the controller's data channel while waiting for an interrupt 
or timeout so that other units on the controller can start their 
operations. 


9.4.1 WFIKPCH and WFIRLCH Macro Formats 

A start-I/O routine invokes either the WFIKPCH or WFIRLCH 
macro to wait for a device interrupt. 

Formats 

WFIKPCH excpt,[time] 

WFIRLCH excpt,[time] 
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excpt 

The address of the timeout routine for this device. 

time 

The number of seconds to wait before signaling a device 
timeout. The number must be greater than or equal to 2. A 
minimum value of 2 is required because the timeout mechanism 
is accurate only to within one second. If no number is specified, 
the macro uses the value 65,536 by default. 


9.4.2 Expansion of WFIKPCH Macro 

Because the WFIKPCH and WFIRLCH macros are similar, the 
description that follows analyzes the expansion of WFIKPCH 
only. 

If the driver specifies the time argument in the macro call, the 
macro pushes the value of the argument into the stack. If the 
time argument is not specified, the macro pushes the value 
65,536 onto the stack. 

The VAX/VMS timer routine uses the time value to calculate 
the length of time to wait before transferring control to a device 
timeout handler. 

WFIKPCH completes its expansion with two lines of code: 

JSB G~IOC$WFIKPCH 
.WORD EXCPT-. 

The execution of the JSB instruction pushes the address 
following the JSB onto the stack as the address to which the 
called routine would normally return with an RSB instruction. 


9.4.3 IOC$WFIKPCH Routine 

The VAX/VMS routine IOC$WFIKPCH invoked by the 
macro WFIKPCH performs the functions necessary for the 
driver fork process to wait for a device interrupt or timeout. 
IOC$WFIKPCH first adds 2 to the address on the top of the 
stack so that the top of the stack contains the address of the 
next instruction in the driver after the macro invocation. This 
address is where the driver resumes execution as a result of an 
interrupt-servicing routine's JSB instruction. 
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IOC$WFIKPCH then saves the contents of R3, R4, and the 
address to which control must be returned to the driver, which 
it takes from the top of the stack. It saves this information in 
the first part of the unit-control block, in the UCB fork block. 


Note that after an interrupt the interrupt-servicing routine must 
restore R5 so that it contains the address of the unit-control 
block. The interrupt-servicing routine normally obtains the 
address of the unit-control block from the field IDB$L_OWNER 
of the interrupt-dispatch block. 


The VAX/VMS routine that detects a device timeout calculates 
the address of the driver's timeout routine by subtracting 2 from 
the saved PC in the UCB's fork block and calling indirectly 
through the result, for example: 


MOVL 

UCB$L_FPC(R5),R2 

CVTWL 

-(R2).-(SP) 

ADDL 

(SP)+,R2 

JSB 

(R2) 


Get saved PC 

Get offset to timeout 

handler 

Add to relative driver 
address to obtain relative 
handler address 
Call timeout handler 


IOC$WFIKPCH sets bits in the unit-control block (UCB$V_INT 
and UCB$V_TIM in UCB$L_STS) to indicate that interrupts 
and timeouts are expected from the device. IOC$WFIKPCH 
also writes the device timeout absolute time in the field 
UCB$L_DUETIM. The absolute time is the number of seconds 
since the operating system was bootstrapped plus the number 
of seconds specified in the time argument to the macro. 

Finally, IOC$WFIKPCH reenables interrupts by lowering IPL to 
fork level, the IPL at which the driver was executing previously. 
Then it returns control to the caller of the driver. 


9.5 Responding to an Expected Device Interrupt 

The only context saved for the driver is now in the unit-control 
block. It contains the following information: 

• A description of the I/O request and the state of the device 

• The contents of R3 and R4 

• The implicit contents of R5 (the address of the UCB fork 
block) 
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• The address at which to return control to the driver 

• The implicit address of a device-timeout routine 

By convention, R4 often contains the address of the control 
/status register; it permits the driver's interrupt-servicing 
routine to examine device registers. When the driver's fork 
process regains control after an interrupt processing, R5 
contains the UCB address. The UCB is the key to that part 
of the I/O database relevant to the current I/O operation. 

When a device interrupts, the driver's interrupt-servicing 
routine analyzes the interrupt, as detailed in Chapter 11 and 
summarized below: 

• Identifies the address of the UCB of the device that 
generated the interrupt 

• Obtains device-status or controller-status information from 
the device registers, if necessary, and stores the status 
information in the unit-control block 

• Restores the driver's fork process's registers from the 
UCB fork block, restores R5 with the UCB address, and 
reactivates the suspended driver at the PC stored in the 
UCB fork block 

If, instead of requesting an interrupt, the device times out, a 
VAX/VMS timer routine reactivates the suspended driver fork 
process at the address of the timeout routine. Section 12.2 
discusses device timeout handling in detail. 
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A driver performing DMA transfers over the UNIBUS must 
take UNIBUS operation into consideration. The VAX/VMS 
operating system and the I/O database handle most UNIBUS 
mapping register and data path resource management for the 
device drivers. 


You must choose the type of data path (either direct or 
buffered) appropriate to the device and ensure that UCB 
fields are written to describe the virtual memory locations 
to be read or written. Once these actions have been taken, the 
driver's fork process calls VAX/VMS routines to take care of 
the detailed operation of the UNIBUS adapter. 


The I/O database contains an adapter-control block (ADP) that 
describes the UNIBUS adapter. This block contains allocation 
information for the UNIBUS adapter data paths and mapping 
registers. 


The adapter-control block also contains the virtual address of 
the UNIBUS adapter's configuration register. All the adapter's 
other registers are located at fixed offsets from the configuration 
register. The VAX/VMS UNIBUS-adapter-handling routines 
modify the UNIBUS adapter's data-path register and mapping 
registers according to requests from driver's fork processes. 


In general, drivers' fork processes do not access the adapter- 
control blocks. Instead, drivers call VAX/VMS routines that 
perform adapter-related services, such as the following: 

• Allocating a buffered data path 

• Allocating mapping registers 

• Loading mapping registers 

• Deallocating mapping registers 

• Purging a buffered data path 

• Deallocating a buffered data path 
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The system creates a driver's fork process by calling the start- 
I/O routine in a device driver. The fork process takes some or 
all the following steps to initiate an I/O transfer on a UNIBUS 
device: 

1 Requests buffered data path 

2 Requests mapping registers 

3 Loads mapping registers 

4 Calculates starting UNIBUS address 

5 Activates device 

6 Waits for interrupt 

When a hardware interrupt indicates that the I/O transfer is 
complete, the driver's fork process checks the success or failure 
of the transfer. The driver then concludes with the following 
steps: 

1 Purges the buffered data path 

2 Releases the data path 

3 Releases the mapping registers 

All of the steps above involve the UNIBUS adapter. VAX/VMS, 
however, hides most of the UNIBUS interfacing from the driver. 


10.1 Requesting a Buffered Data Path 

The system allows a driver to request temporary or permanent 
allocation of a buffered data path. After the driver fork 
process gains access to the controller (see Section 9.3.1), it 
requests a buffered data path by invoking the VAX/VMS 
macro REQDPR. REQDPR calls a VAX/VMS routine named 
IOC$REQDATAP that locates the adapter-control block. To do 
this, IOC$REQDATAP uses a series of pointers that begin in 
the current unit-control block, as follows: 

UCB —> CRB —> ADP 

> 
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The ADP's data-path-allocation information indicates which 
buffered data paths are available. IOC$REQDATAP allocates 
a data path to the driver by storing the data path number 
in the channel-request block and indicating in the adapter- 
control block (ADP) that the data path is in use. Then, control 
returns to the driver fork process. Appendix A describes the 
adapter-control block. 

If no data path is available, IOC$REQDATAP saves driver 
context (R3, R4, and PC) in the UCB fork block and inserts 
the address of the fork block, which is also the address of the 
unit-control block and the content of R5, in the ADP's data¬ 
path-wait queue. The driver fork block remains in the queue 
until both of the following conditions are met: 

• A data path is available. 

• The driver fork block is the next entry in the data-path-wait 
queue. 

When these conditions are met, the VAX/VMS routine 
IOC$RELDATAP allocates the data path to the suspended 
driver and reactivates the driver's fork process. 


10.1.1 Requesting a Permanent Buffered Data Path 

A device driver can permanently allocate a buffered data 
path with code in a unit-initialization routine. Three steps 
permanently allocate a buffered data-path: 

1 Test the path-lock bit (VEC$V_PATHLOCK) in the data¬ 
path-number field of the channel-request block (CRB$L_ 
INTD+VEC$B_DATAPATH) to ensure that a data path is 
not already allocated for this device. 

2 Call the subroutine IOC$REQDATAPNW to allocate the 
data path as shown below: 

JSB G~IOCSREQDATAPNW 

If IOCSREQDATAPNW successfully allocates the data path, 
it stores the number of the data path it obtained in the 
channel-request block at VEC$B_DATAPATH and returns 
with the low-order bit set in RO. If IOCSREQDATAPNW 
cannot allocate a data path, it returns with the low-order bit 
clear in RO. 
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3 Set the path-lock bit (VEC$V_PATHLOCK) in the channel- 
request block at VEC$B_DATAPATH 

The driver-loading procedure calls the unit-initialization routine 
for each unit that the driver serves. A unit-initialization routine 
that contains the code described above will permanently 
allocate one buffered data path for each CRB associated with 
the driver, which is one path for each controller that the driver 
serves. 

Some VAX processors have a small number of buffered data 
paths. If device drivers running on these processors do not limit 
permanent allocation of buffered data paths, the system might 
not have any paths left for its own use. For example, the VAX- 
11/750 has three buffered data paths. If device drivers loaded 
on this machine permanently allocate all three data paths, 
the operating system will have no buffered data paths left for 
normal operations. In this case, I/O transfers that require a 
buffered data path will wait forever. 


10.1.2 Requesting the Direct Data Path 

Because the UNIBUS adapter arbitrates among devices that 
wish to use the direct data path and because the CRB is 
initialized to 0 (0 = direct data path), drivers are not required to 
invoke the REQDPR macro to request the direct data path. 

Some VAX processors, such as the VAX-11/780, do not 
permit byte-offset transfers on the direct data path. On these 
processors, drivers for word-aligned devices must ensure that 
the data buffer is aligned on a word boundary. 


10.1.3 Mixed Use of Direct and Buffered Data Paths 

A device driver can use the buffered data path for certain 
operations, then use the direct data path for other operations. 
To accomplish this task, the driver should allocate a buffered 
data path for buffered I/O. When the operation is completed, 
the driver should then purge and release the buffered data 
path. The release automatically resets the data path number to 
zero, which signifies a direct data path. The driver should not 
release the direct data path, although it should purge the path. 
(A purge of the direct data path is a NOP and always yields 
success.) 
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10.2 Requesting UNIBUS Adapter Mapping Registers 

The operating system allows a driver to allocate mapping 
registers as needed or to allocate them permanently. 


10.2.1 Allocation of Mapping Registers 

After the driver's fork process gains access to the controller (see 
Section 9.3.1), it requests a set of UNIBUS adapter mapping 
registers by invoking the VAX/VMS macro REQMPR. This 
macro calls the routine IOCSREQMAPREG. IOCSREQMAPREG 
calculates the number of mapping registers needed for a 
transfer. The calculation is based on the transfer byte count 
field and the byte offset fields of the device's unit-control block 
(UCB$W_BCNT and UCB$W_BOFF). 

The procedure for allocating mapping registers is similar to that 
used to allocate a buffered data path. First, IOCSREQMAPREG 
locates the adapter-control block from a series of pointers that 
begin with the current unit-control block, as follows: 

UCB --> CRB --> ADP 

Then, the routine examines the mapping-register-allocation 
information to locate the required number of contiguous 
mapping registers. If the registers are not currently available, 
IOCSREQMAPREG saves the driver context (R3, R4, and PC) 
in the UCB fork block and inserts the fork block's address 
(same as UCB address and the contents of R5) in the mapping- 
register-wait queue. 

When the mapping registers are available, IOCSREQMAPREG 
allocates them and adjusts the appropriate information about 
the allocation of mapping registers in the adapter-control block. 
IOCSREQMAPREG then writes the number of the first mapping 
register and the number of mapping registers allocated into the 
channel-request block and returns control to the driver's fork 
process. 
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10.2.2 Permanent Allocation of Mapping Registers 

A device driver can permanently allocate a set of mapping 
registers with code in the unit-initialization routine. The 
number of mapping registers permanently allocated must 
be sufficient for the longest possible transfer. The following 
steps permanently allocate a set of mapping registers: 

1 Test the map-lock bit (VEC$V_MAPLOCK) in the channel- 
request block (CRB$L_INTD+VEC$W_MAPREG). 

2 Load the number of mapping registers required into R3. 

3 Call the VAX/VMS routine IOC$ALOUBAMAPN with a 
JSB instruction: 

JSB G~I0C$AL0UBAMAPN 

If IOC$ALOUBAMAPN successfully allocates the mapping 
registers, it stores the number of mapping registers allocated 
and the number of the first of the allocated mapping 
registers. It stores these items in the channel-request 
block at CRB$L_INTD+VEC$B_NUMREG and CRB$L_ 
INTD+VEC$W_MAPREG, respectively, and returns with the 
low-order bit set in RO. 

Otherwise, it returns with the low-order bit of RO clear. 

4 Set the map-lock bit in the channel-request block (VEC$V__ 
MAPLOCK in CRB$L_INTD+VEC$W_MAPREG). 

The driver-loading procedure calls the unit-initialization routine 
once for each unit associated with the driver. If the unit 
initialization routines contains the code described above, it 
permanently allocates one set of mapping registers for each 
CRB associated with the driver, which is one set of registers for 
each device controller that the driver serves. 
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10.3 Loading the UNIBUS Adapter's Mapping Registers 

Once a driver's fork process has assigned a data path and 
allocated a set of mapping registers, it can request VAX/VMS to 
load the mapping registers with physical-page-frame numbers 
by invoking the VAX/VMS macro LOADUBA. LOADUBA calls 
a VAX/VMS routine IOC$LOADUBAMAP that loads each 
allocated mapping register with five data items: 

• A bit setting to indicate whether the mapping register is 
valid. 

• A bit setting to indicate whether the transfer is to start on 
the odd or even byte within a word; this bit is set if the 
low-order bit of UCB$W_BOFF is a 1. 

• The number of the data path to use for the transfer. 

• The page-frame number of a page in memory. 

• A bit setting to indicate that the transfer operates in 
longword-aligned, random-access mode; this bit is set 
when VEC$V_LWAE is set in VEC$B_DATAPATH. 

IOC$LOADUBAMAP loads the page-frame number of the first 
page of the transfer into the first allocated mapping register, the 
page-frame number of the second page of the transfer into the 
second mapping register, and so forth. 

IOC$LOADUBAMAP sets the valid bit in every allocated 
mapping register except the last. It clears the valid bit in the 
final mapping register to prevent a prefetch from an invalid 
page. 

To calculate the page-frame number used in the I/O transfer, 
IOC$LOADUBAMAP uses three fields that VAX/VMS has 
written into the unit-control block: 

• UCB$W_BOFF—Byte offset in the first page of the transfer 

• UCB$W_BCNT—Number of bytes to transfer 

• UCB$L_SVAPTE—Virtual address of the page-table entry 
that contains the page-frame number of the first page of the 
transfer 
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IOC$LOADUBAMAP determines the data path's number, the 
number of the first mapping register, the address of the first 
mapping register, and the number of mapping registers from 
the channel-request block and the UNIBUS adapter-control 
block, as follows: 

UCB --> CRB --> number of the data path 

UCB --> CRB --> number of first mapping register 

UCB —> CRB --> ADP —> virtual address of first mapping register 

UCB --> CRB --> number of mapping registers 


Drivers that handle byte-addressable UNIBUS devices call 
the routine IOC$LOADUBAMAPA. This routine performs the 
same function as IOC$LOADUBAMAP, with one exception. 
When IOC$LOADUBAMAPA loads mapping registers, it clears 
the byte-offset bit even if the transfer begins on an odd-byte 
address. 

When IOC$LOADUBAMAP has loaded all the mapping 
registers and marked the last mapping register invalid, it 
returns control to the driver's fork process. 


10.4 Computing the Starting Address of a Transfer 

The driver fork process must calculate the starting address of a 
UNIBUS transfer and load this address into the appropriate 
device register. The driver takes five steps to make the 
calculation: 

1 Writes the byte-offset-in-page field of the UCB (UCB$W_ 
BOFF) into bits 0 through 8 of a register 

2 Gets the number of the starting mapping register for the 
transfer from the channel-request block; the number is a 
9-bit value 

3 Writes bits 0 through 6 of the mapping register number into 
bits 9 through 15 of the register containing the byte offset 
field 
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4 Writes bits 0 through 15 of the register into the buffer 
address register for the device 

5 Writes bits 7 and 8 of the mapping register number into 
the extended memory bits of the appropriate device register 
(usually the control/status register) 
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10.5 Activating the Device 

Because a driver's fork process can address device registers as 
though they were any other virtual address, the loading of the 
UNIBUS buffer address register and control/status register are 
simple procedures. The driver locates the CSR address of the 
device in the interrupt-data block, as follows: 

UCB --> CRB —> IDB —> CSR address 

The CSR address is the virtual address of a device register. All 
other device registers are located at constant offsets from the 
CSR address. If, for example, the control/status register is the 
first device register and the device's word-count register is the 
third device register, the device driver can load the word count 
register with the following sequence of instructions: 

• Move the CSR address into R4. 

• Use a MOVW instruction to move the number of words to 
transfer into the address 4(R4). 



10.6 Completion of a DMA Transfer 

After a driver's fork process activates a DMA UNIBUS device, 
the driver waits for a device interrupt by invoking a VAX/VMS 
macro that suspends execution of the driver. When the 
UNIBUS device requests a hardware interrupt, the interrupt 
dispatcher gains control. 

The dispatcher saves RO through R5 and transfers control to the 
driver's interrupt-servicing routine. If the interrupt-servicing 
routine can match the interrupt with a suspended driver's fork 
process, the interrupt-servicing routine reactivates the driver's 
fork process at the point where execution was suspended. 

The driver almost immediately invokes the VAX/VMS macro 
IOFORK. 

IOFORK calls the VAX/VMS routine EXE$IOFORK. 
EXE$IOFORK saves the driver context (R3, R4, and PC) in the 
UCB fork block and inserts the address of the fork block (R5) 
in the device's fork queue. EXE$IOFORK then returns control 
to the driver's interrupt-servicing routine, which dismisses the 
interrupt. 



10-10 







Writing UNIBUS DMA Transfers 


When the fork dispatcher reactivates the driver's fork process, 
the driver performs any necessary UNIBUS adapter clean-up 
operations, such as purging the data path and deallocating 
UNIBUS adapter resources used in the DMA transfer. 


10.6.1 Purging the Data Path 

Driver fork processes must purge the data path after the DMA 
transfer is complete. This is true for devices with buffered data 
paths, direct data paths, or no data path. 

To purge the data path, the driver invokes the macro PURDPR, 
which in turn calls the VAX/VMS routine IOC$PURGEDATAP. 
This routine takes the following steps to purge the data path: 

1 Saves the contents of R4 on the stack. 

2 Locates the channel-request block as follows: 

R5 — > UCB --> CRB 

3 Obtains the starting address of UNIBUS adapter register 
space and stores it in R2. 

4 Extracts the number of the data path to be purged from the 
channel-request block and loads it into Rl. 

5 Stores the address of the data path in R4. 

6 Instructs the UNIBUS adapter to purge the data path. 

The routine then modifies RO through R2 to contain the 
following information: 

RO Success/failure status. If the purge completes without 
error, the routine sets SS$_NORMAL in this register. If a 
data path error does occur, RO is clear and the hardware 
is reset. 

Rl Contents of the data path register. 

R2 Address of the first UNIBUS adapter mapping register. 

The address of the channel-request block remains in R3. 
This address, along with the information in Rl and R2, is 
used as input to the error-logging routine in the event of a 
data-path error. 
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7 Restores the information stored on the stack to R4 and 
returns to PURDPR. 

8 Some machine implementations also check for memory 
errors that might have occurred during the DMA operation, 
and, if an error is detected, log it. 

If a data-path error occurs during a data-path purge, the driver 
should retry the entire DMA transfer. 


10.6.2 Releasing a Buffered Data Path 

A driver's fork process releases a buffered data path by 
invoking the VAX/VMS macro RELDPR. RELDPR calls a 
VAX/VMS routine IOCSRELDATAP that determines which 
data path was assigned to the driver fork process and releases 
the data path to a waiting driver. The driver must be executing 
at fork IPL. 

The data path number is stored in the channel-request block. 
IOCSRELDATAP locates it as follows: 

UCB —> CRB —> number of the data path 

If the data path is permanently assigned to a device, 
IOCSRELDATAP does not release the data path. Otherwise, 
the data path number in the channel-request block (CRB$L_ 
INTD + VEC$B_DATAP) is zeroed. The IOCSRELDATAP 
routine attempts to dequeue a waiting driver fork process from 
the data-path-wait queue. It finds the queue as follows: 

UCB —> CRB —> ADP —> Data-path-wait queue 

If another driver is waiting for a buffered data path, 
IOCSRELDATAP grants that driver fork process the data 
path, restores its context from its UCB fork block, and transfers 
control to the saved driver PC. When IOCSRELDATAP can 
allocate no more data paths, the routine returns to the driver 
that released the data path. This diversion of driver processing 
is transparent to the driver's fork process. 

If the data-path-wait queue is empty, IOCSRELDATAP marks 
the data path as available in the adapter-control block and 
returns control to the driver. 
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10.7 Releasing UNIBUS Adapter Mapping Registers 

A driver fork process releases a set of UNIBUS adapter mapping 
registers by invoking the VAX/VMS macro RELMPR at fork 
IPL. RELMPR calls the VAX/VMS routine IOC$RELMAPREG, 
which releases mapping registers in a manner similar to the 
way in which the RELDPR macro releases data paths. The 
channel-request block records the number of mapping registers 
assigned to the device. The number of the first mapping register 
and the number of mapping registers are located as follows. 

UCB --> CRB —> Number of the first mapping register 
UCB —> CRB --> Number of mapping registers allocated 

IOC$RELMAPREG releases the mapping registers by adjusting 
the mapping-register-allocation information in the adapter- 
control block. 

Then, IOC$RELMAPREG attempts to dequeue a driver's fork 
process from the mapping-register-wait queue. If a suspended 
driver is found, IOC$RELMAPREG takes the following steps: 

1 Dequeues the fork block and restores driver context 

2 Satisfies the mapping-register request, if possible 

3 Reactivates the driver's fork process at the instruction 
following the driver's request for mapping registers 

4 Returns control to the driver's fork process 

If the mapping-register-wait queue is empty or if 
IOC$RELMAPREG still does not have enough contiguous 
mapping registers for any of the waiting fork processes, it 
returns control to the fork process that released the mapping 
registers. 
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For most device drivers, driver-prologue table contains, in 
the reinitialization section established using the DPT—STORE 
macro, the address of one or more interrupt-servicing routines. 
Each interrupt-servicing routine corresponds to an interrupt 
vector on the UNIBUS. You specify the UNIBUS vector's 
address using the SYSGEN command CONNECT, as described 
in Chapter 14. 

Most interrupt-servicing routines in device drivers perform the 
following functions: 

• Locate the device's unit-control block 

• Determine whether the interrupt was solicited 

• Reject or process unsolicited interrupts 

• Activate the suspended driver to process solicited interrupts 

Figure 11-1 illustrates the general flow of interrupt handling. 
The remaining sections of this chapter describe the handling of 
solicited and unsolicited interrupts in further detail. 


11.1 Delivering a Device Interrupt to a Driver 

When a UNIBUS device generates a hardware interrupt, the 
device requests the interrupt at its device IPL. The UNIBUS 
adapter then requests a processor interrupt at that IPL. When 
the processor executes at an interrupt priority level below the 
device IPL, interrupt dispatching begins. 

On a configuration that uses nondirect-vector interrupts, the 
following sequence occurs: 

• The processor saves, on the interrupt stack, the PC and PSL 
of the currently executing code and transfers control to the 
VAX/VMS UNIBUS adapter's interrupt-servicing routine. 
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• The UNIBUS adapter's interrupt-servicing routine reads the 
vector register within the UNIBUS adapter that corresponds 
to the interrupt level of the device. The UNIBUS adapter 
acknowledges the interrupt, and the interrupting device 
supplies its vector's address to the UNIBUS adapter's 
interrupt-servicing routine. 

• The UNIBUS adapter's interrupt-servicing routine then saves 
RO through R5 on the stack and, using a JMP instruction, 
transfers control to an interrupt-dispatching field within the 
channel-request block. 


• The CRB's interrupt-dispatching field (CRB$L_INTD+2) 
contains executable code that the driver-loading procedure 
has associated with the interrupting vector. Interrupt¬ 
dispatching fields for nondirect vectors contain the following 
executable instruction: 

JSB Q#address-of-driver-isr 


On a configuration that uses direct vector interrupts, the 

following sequence occurs: 

• The processor saves, on the interrupt stack, the PC and 
PSL of the currently executing code and acknowledges the 
device's interrupt. 

• The UNIBUS device supplies its vector address, which the 
processor uses as an index into a table of addresses in the 
second (or third) page of the system-control block (see 
Section 3.1.6). 

• When the processor locates the address in the SCB that 
corresponds to the vector address, it transfers control to an 
interrupt-dispatching field in the channel-request block. 

• The CRB interrupt-dispatching field (CRB$L_INTD) contains 
executable code that the driver-loading procedure has 
associated with the interrupt vector. Interrupt-dispatching 
fields of direct vectors contain the following executable 
instructions: 

PUSHR <R0,R1,R2,R3,R4,R5> 

JSB <a#addre88-of-driver-isr 
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Figure 11—1 Interrupt Handling Flow 
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The driver-loading procedure determines how many interrupt¬ 
dispatching fields to build within the CRB from the number of 
vectors specified in the /NUMVEC qualifier to the SYSGEN 
command CONNECT (see Section 14.2.2). The driver-loading 
procedure obtains the address of the interrupt-servicing routine 
for each interrupt-dispatching field from the reinitialization 
portion of the driver-prologue table. This section of the DPT 
contains one or more DPT_STORE macros that identify the 
addresses of the interrupt-servicing routines. The number of 
DPT—STORE macros that identify interrupt-servicing routines 
must equal the number of vectors given in the /NUMVEC 
qualifier to avoid errors in device initialization or interrupt 
handling. 

Immediately following the JSB instruction in the channel- 
request block is the address of the interrupt-dispatch block 
associated with the CRB. When the JSB instruction executes, a 
pointer to the address of the interrupt-dispatch block is pushed 
onto the top of the stack as though it were a return address. 
The driver interrupt-servicing routine can use this IDB address 
as a pointer into the I/O database. Figure 11-2 illustrates the 
portion of a channel-request block that contains the address of 
the interrupt-servicing routine. 


11.2 Interrupt Context 

When the interrupt dispatcher calls a driver's interrupt-servicing 
routine, execution context is as follows: 

• RO through R5 are saved on the stack. 

• System address space is mapped. The interrupt-servicing 
routine can gain access to appropriate control blocks in the 
I/O database. 

• IPL is at hardware device interrupt level. 

• The processor is running in kernel mode. 

• The processor is running on the interrupt stack. 
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The stack contains the following information: 


Stack Location 

Content 

O(SP) 

Pointer to the address of the 
interrupt-dispatch block 

4(SP) through 24(SP) 

Saved RO through R5 

28(SP) 

PC at the time of the interrupt 

32(SP) 

PSL at the time of the interrupt 


Figure 11-2 Channel-Request Block Containing the Address of 
an Interrupt-Servicing Routine 


CHANNEL REQUEST BLOCK: 


JSB @# | 

INTERRUPT SERVICE ROUTINE ADDRESS 
INTERRUPT DISPATCH BLOCK ADDRESS 


11.3 Servicing a Solicited Interrupt 

When a driver's fork process activates a device and expects to 
service a device interrupt as a result, the fork process suspends 
its execution and waits for an interrupt to occur. The suspended 
driver is represented only by the contents of the device's unit- 
control block, which contains a description of the I/O request 
and the fork process. 

When the driver regains control from the interrupt-servicing 
routine, only R3, R4, R5, and the PC address are restored to 
their previous state by the interrupt-servicing routine. 
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In the sequence below, a driver's interrupt-servicing routine 
returns control to the waiting driver: 

1 The interrupt-servicing routine obtains the address of the 
device's unit-control block from the interrupt-data block, as 
follows: 

O(SP) --> CRB --> IDB —> IDB$L_OWNER —> UCB for the device 

2 The interrupt-servicing routine then tests the software- 
interrupt-expected bit in the UCB status word (UCB$V_INT 
in UCB$L_STS). If the bit is set, the driver is waiting for an 
interrupt from this device. The interrupt-servicing routine 
then clears UCB$V_INT in UCB$W_STS to indicate that it 
has received the expected interrupt. 

3 The interrupt-servicing routine restores R5 of the driver's 
fork process, placing in it the address of the UCB fork 
block. It restores R3 and R4 of the driver process by placing 
in them the contents of UCB$L_FR3 and UCB$L_FR4, 
respectively. 

4 The interrupt-servicing routine transfers control to the 
driver's PC address, which is saved in the UCB fork block at 
UCB$U_FPC, by issuing a JSB instruction. 

The restored driver can execute a few instructions in the context 
of the interrupt, such as copying device-status information from 
the device registers into the device's UCB. Before completing 
the I/O operation, however, the driver routine creates a fork 
process to lower its IPL from device level to fork level. The 
driver creates a fork process by invoking the VAX/VMS macro 
IOFORK, as described in Section 12.1.1. 

IOFORK calls the VAX/VMS routine EXE$IOFORK. 
EXE$IOFORK inserts into the appropriate fork queue the UCB 
fork block that describes the driver process. Then it returns 
control to the driver's interrupt-servicing routine. 
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The interrupt-servicing routine then performs the following steps: 

1 Removes the IDB pointer from the stack 

2 Restores RO through R5 

3 Dismisses the interrupt with an REI instruction 


11.4 Servicing an Unsolicited Interrupt 

Devices request interrupts to indicate to a driver that the device 
has changed status. If a driver's fork process starts an I/O 
operation on a device, the driver expects to receive an interrupt 
from the device when the I/O operation completes or an error 
occurs. 

Other changes in the device's status occur when the device has 
not been activated by a device driver. The device reports these 
changes by requesting unsolicited interrupts. For example, 
when a user types on a terminal that is not attached to a 
process, the terminal requests an interrupt that is handled by 
the terminal driver. As a result of the interrupt, the terminal 
driver causes the login procedure to be invoked for the user at 
the terminal. 

Another example of an unsolicited interrupt is one that the unit 
requests when an operator changes the volume on a disk drive. 
The disk driver services the interrupt by altering volume and 
unit status bits in the disk device's unit-control block. 

Devices request unsolicited interrupts because some external 
event has changed the status of the device. A device driver can 
handle these interrupts in two ways: 

• Ignore the interrupt as spurious 

• Examine the device registers and take action according to 
their indications of changed status, and then poll for any 
other changes in device status 

The driver's interrupt-servicing routine determines whether 
an interrupt is solicited or not by examining the software- 
interrupt-expected bit in the UCB status word (UCB$V_JNT 
in UCB$L_STS). All UNIBUS device drivers must use this 
method to determine whether or not an interrupt is solicited; 
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the address of the unsolicited-interrupt routine, specified in the 
driver-dispatch table, is used only by MASSBUS drivers. 

If the interrupt is unsolicited, the driver can reject the interrupt 
with the following code sequence: 

1 Remove the IDB pointer from the stack 

2 Restore RO through R5 

3 Dismiss the interrupt with an REI instruction 

Rather than rejecting the interrupt, the driver might wish to 
handle it. For example, the driver can send a message to the 
operator or the job controller's mailbox when an unsolicited 
interrupt occurs. 

Drivers should always handle unsolicited interrupts from busy 
devices at device IPL. If a driver must create a fork process to 
handle such an interrupt, it should use extreme caution. The 
unit-control block of a busy device might contain the active 
fork block of a previously created driver fork process. If a 
routine servicing an unsolicited interrupt creates a fork process 
to handle its interrupt, it can destroy the fork context currently 
stored in that unit-control block. 


11.4.1 Examples of Handling Unsolicited Interrupts 

A card reader requests an unsolicited interrupt when a user 
turns the reader on line. Once the card-reader driver's 
interrupt-servicing routine determines that the interrupt 
is unsolicited, the routine analyzes the interrupt, as in the 
following example: 

• It obtains the address of the control/status register using the 
interrupt-dispatch block to which the address on the top of 
the interrupt stack points, as follows: 

O(SP) --> CRB —> IDB --> IDB$L_CSR —> CSR for the device 

Because the card reader has a dedicated controller, the 
IDB$L_OWNER field always points to the single UCB for 
the card reader: 

O(SP) --> CRB —> IDB --> IDB$L_OWNER —> UCB for the device 
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• It confirms that the interrupt is unsolicited by testing the 
interrupt enable bit in the UCB status word (UCB$V_INT in 
UCB$L_STS). 

• Because the interrupt is unsolicited, the routine clears all 
control/status register bits except for the interrupt enable 
bit. 

• It confirms that the reader was just placed on line by 
examining a saved copy of the control/status register. 

• It examines the reference count field of the device's unit- 
control block (UCB$W_JREFC) to determine whether a 
process has allocated the device or assigned a channel to it. 

• If the reference count is zero, the interrupt-servicing routine 
tests the job-attached bit in the device-dependent status field 
(UCB$V_JOB in UCB$W_DEVSTS) to make sure it has not 
already sent the job controller a message about the card 
reader being placed on line. By using the job-attached bit to 
synchronize message sending, the interrupt-servicing routine 
protects the send-message-to-job-controller function from 
the adverse effects of frequent on line interrupts. 

• If the job-attached bit is not set, the routine sets the bit 
and creates a fork process to send the message to the job 
controller. The message says that the card reader has come 
on line. Only one sequence of instructions can use the UCB 
as a fork block. Therefore, the interrupt-servicing must 
perform the following steps before it can create the fork 
process: 

— Ensure that no one is using the card reader, and that no 
one wants to use it, by determining that the reference 
count (UCB$W_REFCNT) is zero. 

— Ensure that it is not already using the UCB, to create a 
fork process in order to lower IPL and to send a message 
to the job controller, by testing the job-attached bit 
(UCB$V_JOB in UCB$W_DEVSTS). 

The VAX/VMS routine that creates the fork process (once 
the above conditions are satisfied) returns control to the 
interrupt-servicing routine. 

• When the interrupt-servicing routine regains control, it 
restores RO through R5 and dismisses the interrupt with an 
REI instruction. (The interrupt-servicing routine removed 
the IDB pointer from the stack earlier in its execution in 
order to obtain CSR and UCB addresses.) 
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If a fork process was created, it executes after IPL drops 
below UCB$B_FIPL. The fork process writes the message to 
the job controller's mailbox, indicating that the card reader 
is on line. The fork process cannot send the message at 
device IPL or any IPL greater than IPL$_MAILBOX. 

If the send-message request fails, the fork process clears 
the job-attached bit so that the job controller will receive a 
message if any change in the card reader's state occurs. If 
the fork process successfully sends the message, it leaves 
the job-attached bit set to prevent the job controller from 
receiving any further messages about the card reader's state. 
(The driver's cancel-I/O routine later clears the bit.) 

Another example of unsolicited interrupt processing occurs in 
a device driver for a multiunit controller. When the operator 
removes a disk volume, the disk drive requests an interrupt. 
The driver interrupt-servicing routine must determine what 
drive unit requested the interrupt, obtain status information 
from the drive's control/status register, and then decide 
whether the interrupt was solicited. 

If the interrupt is unsolicited, the driver's interrupt-servicing 
routine calls its unsolicited-interrupt routine. The routine 
checks the status of the volume, as described in the following 
steps: 

1 It sets a bit in the unit-control block to indicate that the unit 
is on line (UCB$V_ONLINE in UCB$W_STS). 

2 If the UCB's volume-valid bit is set (UCB$V_VALID in 
UCB$L_STS), the routine tests the volume valid status bit 
in a device register to determine whether the volume status 
has changed. If the volume is no longer valid, the routine 
clears the UCB volume valid bit. 

3 The routine returns control to the driver's interrupt-servicing 
routine. 

The driver's interrupt-servicing routine then polls the other 
device units on the controller to determine whether any 
other units requested interrupts while the first interrupt was 
being processed. When no unit requires interrupt servicing, 
the routine removes the IDB pointer from the stack, restores 
registers RO through R5, and dismisses the interrupt with an 
REI instruction. 
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Once a driver has activated the device and invoked the wait for 
interrupt macro, the driver remains suspended until one of the 
following events occurs: 

• The device requests an interrupt. 

• The device times out. 

If the device requests an interrupt, the driver interrupt¬ 
servicing routine handles the interrupt and then reactivates 
the driver at the instruction following the wait for interrupt 
macro. The reactivated driver performs device-dependent I/O 
postprocessing. 

If the device does not request an interrupt within the designated 
time interval, the system transfers control to the driver's timeout 
handler. The address of the timeout handler is specified as an 
argument to the wait-for-interrupt macro invocation. 


12.1 I/O Postprocessing 

Once the driver interrupt-servicing routine has handled an 
interrupt, it transfers control to the driver by issuing a JSB 
instruction. At this point, the driver is executing in interrupt 
context. If the driver were to continue executing in interrupt 
context, it would lock out most other processing on the 
processor including the handling of hardware interrupts. 

To restore the driver to the context of a driver fork process, 
the driver invokes the VAX/VMS macro IOFORK. Once the 
fork process has been created and dispatched for execution, it 
executes the driver code that completes the processing of the 
I/O request. 
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12.1.1 EXE$IOFORK 

IOFORK is a macro that generates a call to the VAX/VMS 
routine EXE$IOFORK. EXE$IOFORK converts the driver context 
from that of an interrupt-servicing routine to the context of a 
driver fork process in the following steps: 

1 It disables software timeouts by clearing the timeout enable 
bit in the UCB status word (UCB$V_TIM in UCB$L_STS). 

2 It saves R3 and R4 of the current driver context in the UCB 
fork block (UCB$L_FR3 and UCB$L_FR4). 

3 EXE$IOFORK then saves the current driver PC in the 
UCB fork block (UCB$L_FPC). The driver PC is the first 
longword on the stack upon entry to EXE$IOFORK as a 
result of the JSB instruction. 

4 It obtains the fork IPL of the device from the UCB (UCB$B_ 
FIPL). 

5 It inserts the address of the UCB fork block (R5) into the 
fork queue corresponding to the driver's fork IPL. 

6 Finally, if the fork block is the first entry in the fork queue, 
EXE$IOFORK requests a software interrupt at the driver's 
fork IPL. 

The steps listed above move the fork process's context into the 
UCB's fork block. They save R3 through R5 and the driver's 
PC address. The driver's fork process resumes processing when 
the VAX/VMS fork dispatcher dequeues the UCB fork block 
from the fork queue and reactivates the driver at the driver's 
fork IPL. 
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12.1.2 Completing an I/O Request 

When VAX/VMS reactivates a driver's fork process by 
dequeuing the fork block, the driver resumes processing of the 
I/O operation. If the device has completed the I/O operation 
without errors, the driver's fork process for a DMA device 
proceeds as follows: 

1 Purges the buffered data path 

2 Releases the buffered data path 

3 Releases mapping registers 

4 Releases the controller 

5 Saves the status code, transfer count, and device-dependent 
status that is to be returned to the user process in an I/O- 
status block 

6 Returns control to the operating system 

Chapter 10 discusses the first three steps listed above because 
they relate to UNIBUS DMA transfers. The sections that follow 
describe the remaining three steps. 


12.1.2.1 Releasing the Controller 

To release the controller channel, the driver code invokes the 
VAX/VMS macro RELCHAN. RELCHAN calls the VAX/VMS 
routine IOC$RELCHAN. If another driver is waiting for the 
controller channel, IOC$RELCHAN grants that driver's fork 
process the channel, restores its context from the UCB fork 
block, and transfers control to the saved PC. When no more 
drivers are awaiting the channel, IOC$RELCHAN returns 
control to the fork process that released the channel. 

Drivers for devices with dedicated controllers need not release 
the controller's data channel (as discussed in Sections 9.3.1 and 
13.1). Through code in the unit-initialization routine, these 
drivers set up the device's unit-control block so that the device 
owns the controller permanently. 

Drivers must be executing at driver's fork IPL when they invoke 
RELCHAN or call IOC$RELCHAN. 
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12.1.2.2 Saving Status, Count, and Device-Dependent Status 

To save the status code, transfer count, and device-dependent 

status, the driver performs the following steps: 

1 It loads a success status code (SS$_NORMAL) into bits 0 
through 15 of RO. 

2 If the I/O operation performed by the device is a transfer 
function, the driver loads the number of bytes transferred 
into the high-order 16 bits of RO (bits 16 through 31.) 

3 The driver then loads device-dependent status information, 
if any, into Rl. RO and R1 are the status values that 
VAX/VMS returns to the user process in the I/O-status 
block specified in the original Queue-I/O-Request system 
service. If the user specifies no I/O-status block, VAX/VMS 
does not use RO and Rl. 


12.1.2.3 Returning Control to the Operating System 

Finally, the driver returns control to the system by invoking the 
REQCOM macro to complete the I/O request. REQCOM calls 
the VAX/VMS routine IOC$REQCOM. IOC$REQCOM locates 
the address of the I/O-request packet corresponding to the I/O 
operation in the device's UCB (UCB$L_IRP). It then writes the 
two longwords of completion status contained in RO and Rl 
into the media field of the I/O-request packet (IRP$L_MEDIA 
and IRP$L_MEDIA+4). 

IOC$REQCOM then inserts the I/O-request packet in the 
I/O-postprocessing queue. If the packet is the only entry in 
the postprocessing queue, IOC$REQCOM requests a software 
interrupt at IPL$_IOPOST so the postprocessing begins when 
IPL drops below IPL$_IOPOST. 

If the error-logging bit is set in the device's unit-control block 
(UCB$V_JERLOGIP in UCB$L_STS), IOC$REQCOM obtains 
the address of the error message buffer from the unit-control 
block (UCB$L_EMB). It then writes the following information 
into the error buffer: 

• Final device status (UCB$W__DEVSTS) 

• Final error count (UCB$B_ERTCNT) 

• Two longwords of completion status (RO and Rl) 
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To release the error-message buffer, IOC$REQCOM calls 
ERL$RELEASEMB. Section 13.3 describes error logging in more 
detail. 

If any I/O-request packets are awaiting driver processing, 
IOC$REQCOM performs the following steps: 

1 Dequeues a packet 

2 Creates a new fork process 

3 Activates the driver's start-I/O routine 

Otherwise, IOC$REQCOM clears the unit-busy bit in the 
device's UCB status word (UCB$V_BSY in UCB$U_STS) and 
transfers control to IOC$RELCHAN to release the controller 
channel in case the driver failed to do so. 

The remaining steps in processing the I/O request are 
performed by VAX/VMS I/O postprocessing. 


12.2 Timeout Handlers 

VAX/VMS transfers control to the driver's timeout handler if a 
device unit does not request an interrupt within the time limit 
specified in the invocation of the wait-for-interrupt macro. The 
VAX/VMS timer routine scans device's unit-control blocks once 
every second to determine whether a device has timed out. 

When the timer routine locates a device that has timed out, 
the routine calls the driver's timeout handler by performing the 
following steps: 

1 It disables expected interrupts and timeouts on the device by 
clearing bits in the status field of the device's UCB (UCB$V__ 
INT and UCB$V_TIM in UCB$U_STS). 

2 It sets the device-timeout bit in the UCB status field 
(UCB$V_TIMOUT in UCB$I^STS). 

3 It sets IPL to hardware device interrupt IPL (UCB$B_DIPL). 

4 It restores the saved R3 and R4 of the driver's fork process 
from the UCB fork block (UCB$U_FR3 and UCB$L_FR4). 
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5 It restores R5 (address of the UCB fork block). 

6 It computes the address of the driver's timeout handler from 
the saved PC in the UCB fork block (UCB$L_FPC). 

7 It calls the driver's timeout handler with a JSB instruction. 

The driver's timeout handler executes in following context: 

• RO through R5 are saved on the stack. 

• R5 contains the address of the UCB for the device that timed 
out. 

• System address space is mapped. 

• The processor is running in kernel mode. 

• The processor is running on the interrupt stack. 

• IPL is at hardware device interrupt level. 

VAX/VMS invoked the timeout handler through an interrupt 
at IPL$_TIMER. Thus, the driver can lower from device IPL to 
the driver's fork IPL to process the timeout. (The driver should 
lower IPL with SETIPL to preserve the contents of the stack.) 

When the driver's fork process regains control, R3 and R4 are 
restored to their previous state from UCB$L_FR3 and UCB$L_ 
FR4, respectively. 

During recover from a power failure, VAX/VMS forces a device 
timeout by altering the timeout field (UCB$L_DUETIM) of a 
unit-control block if that device's UCB records that the unit is 
waiting for an interrupt or timeout (UCB$V_INT and UCB$V_ 
TIM set in UCB$L_STS). The timeout handler can perceive that 
recovery from a power failure is occurring by examining the 
power bit (UCB$V_POWER in UCB$L_STS) in the unit-control 
block. 

A timeout handler usually performs one of three functions: 

• Retries the I/O operation unless a retry count is exhausted 

• Aborts the I/O request 

• Sends a message to an operator mailbox and resumes 
waiting for a subsequent interrupt or timeout 


12-6 


Completing the I/O Request 


12.2.1 Retrying the I/O Operation 

Some devices might retry an I/O operation after a timeout. For 
example, a disk driver might take the following steps after a 
transfer timeout: 

1 Invoke the following VAX/VMS macro to lower IPL to fork 
level: 

SETIPL UCB$B_FIPL(R5) 

The resulting IPL must not drop below IPL$_TIMER. 

2 Release mapping registers, data path, and controller data 
channel. 

3 If a power failure occurred, load the address of the I/O- 
request packet into R3, reload the following fields of the 
I/O-request packet into the corresponding UCB fields, and 
branch to the start-I/O routine: 

IRP$W_BCNT 

IRP$W_BOFF 

IRP$L_SVAPTE 

The above steps result in a retry of the transfer from the 
beginning. 

4 If no power failure has occurred and the device driver 
supports error logging, call ERL$DEVICTMO to log the 
device timeout. 

5 If the retry count is not exhausted, decrease the count, 
clear the UCB timeout bit in UCB$L_STS, and retry the 
operation. 

6 If the retry count is exhausted, set the error code, perform a 
normal abort I/O clean-up operation, and invoke REQCOM. 
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12.2.2 Aborting the I/O Request 

A driver's timeout handler aborts the I/O request when it 
exhausts its retry count, or when it determines, upon timeout, 
that a cancel-I/O was requested. If the cancel-I/O bit in the 
UCB status word (UCB$V_CANCEL in UCB$I_STS) is set, 
a cancel-I/O request was made and the timeout handler can 
abort the request. 

To abort an I/O request, a device driver timeout handler can 
perform the following sequence of steps: 

1 If appropriate to the device and controller, the handler clears 
the device control/status register. 

2 The handler then invokes the following VAX/VMS macro to 
lower IPL to fork level: 

SETIPL UCB$B_FIPL(R5) 

The resulting IPL must not drop below IPL$_TIMER. 

3 The handler releases UNIBUS adapter resources and the 
controller data channel, if necessary. 

4 It loads abort status code (SS$_ABORT) into the low word 
of RO. 

5 It clears bits 16 through 31 in RO to indicate that no data 
was transferred. 

6 It invokes the VAX/VMS macro REQCOM, described in 
Section 12.1.2.3, to complete the I/O request processing. 

Because the device can interrupt device-timeout processing 
at fork IPL, the interrupt-servicing routine should check the 
interrupt-expected bit (UCB$V_INT) before handling the 
interrupt. The operating system clears this bit before it calls the 
driver's timeout handler. 
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12.2.3 Sending a Message to the Operator 

The following sequence describes a timeout handler that sends 
a message to the operator's mailbox and then goes back into a 
wait-for-interrupt or timeout state: 

1 It invokes the following VAX/VMS macro to lower IPL to 
driver fork level: 

SETIPL UCB$B_FIPL(R5) 

The resulting IPL must not drop below IPL$_TIMER. 

2 It checks the cancel-I/O bit in the UCB status word 
(UCB$V_CANCEL in UCB$L_STS). If UCB$V_CANCEL is 
not set, the timeout handler performs the following: 

— Saves R3 and R4 on the stack 

— Loads an OPCOM message code, such as MSG$_ 
DEVOFFLIN, into R4 

— Loads the address of the operator's mailbox (SYS$GL_ 
OPRMBX) into R3 

— Calls a VAX/VMS routine to place the message in the 
operator's mailbox, as follows: 

JSB G “ EXE$SNDEVMSG 

— Restores R3 and R4 

(If the cancel-I/O bit is set, the timeout handler can abort 
the request.) 

3 The timeout handler then invokes the VAX/VMS macro 
DSBINT to raise IPL to IPL$_POWER, thereby locking out 
all interrupts from software and hardware. 

4 Finally, the timeout handler invokes the WFIKPCH macro to 
wait for another interrupt or timeout. 

When the OPCOM process reads the message in its mailbox, it 
sends the requested message, in this case "device-offline," to all 
operator terminals. 
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Drivers normally contain initialization, cancel-I/O, and error¬ 
logging routines. The driver-prologue and driver-dispatch 
tables specify the addresses of initialization routines. The 
driver-dispatch table contains the addresses of the cancel-I/O 
and error-logging routines. Whether these routines are required 
depends on the type of device to be driven. 


13.1 Initialization Routines 


Most device controllers and device units require initialization 
under the following circumstances: 



When the driver-loading procedure loads a device driver for 
the controller and device units 


• During recovery from a power failure 


Initialization routines ready controllers and device units 

for operation. Depending on the device's characteristics, 

initialization routines perform any of the actions listed below: 

• Enable controller interrupts. 

• Clear error-status bits in device registers. 

• Initiate a device operation such as clearing a drive or 
acknowledging a pack 

• Store values in UCB fields that DPT_STORE cannot reach. 
The DPT—STORE macro can store values in fields no more 
than 255 bytes from the start of the unit-control block. 

• Permanently allocate UNIBUS adapter resources, as 
described in Chapter 10. 

• Set the online bit (UCB$V_ONLINE in UCB$W_STS) in the 
unit-control block. 



Fill in IDB$L_OWNER for single-unit devices such as line 
printers. 
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13.1.1 Initialization During Driver Loading 

The initialization performed when the driver is loaded depends 
upon whether the driver is being loaded for the first time or is 
replacing a driver that was previously loaded. 

The SYSGEN commands AUTOCONFIGURE, CONNECT, 
and LOAD add new drivers to the configuration. The LOAD 
command loads the driver into nonpaged system memory 
but does not call any driver-specific routines or execute 
any initialization requests specified in DPT_STORE macro 
invocations. AUTOCONFIGURE and CONNECT create the 
I/O data structures associated with the device driver, call 
driver-specific initialization routines, and perform requests 
specified in DPT_STORE macro invocations. 

For each new device they add to the system, 
AUTOCONFIGURE and CONNECT carry out the following 
steps: 

• Create a unit-control block for the device. If this is the first 
occurrence of device-name and controller, the commands 
create a device-data block, a channel-request block, and an 
interrupt-dispatch block. 

• Perform the initialization operations specified by the DPT_ 
STORE macros within the initialization and reinitialization 
portions of the driver-prologue table. 

• Relocate all addresses in the driver-dispatch table and 
function-decision table to system virtual addresses. 

• Call the controller-initialization routine specified in the 
channel-request block, if the CRB was created. 

• Call the unit-initialization routine (if any) specified in the 
driver-dispatch table. If no routine exists in the DDT, call 
the unit initialization routine (if any) specified in the CRB. 

The AUTOCONFIGURE and CONNECT command operations 
raise IPL to IPL$_POWER to prevent interruption of the 
initialization routines. 

The RELOAD command replaces an existing driver with a 
new driver. The command loads the new driver's code 
into nonpaged system memory. Unlike the other SYSGEN 
commands for driver loading, RELOAD assumes that the data 
structures associated with the driver already exist, and thus 
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updates the I/O database to reflect the modified code and its 
different location in system virtual address space. 

The RELOAD command performs the following functions: 

• Executes requests specified by DPT_STORE macro 
invocations in only the reinitialization section of the driver- 
prologue table 

• Relocates all addresses in the function-decision table and 
driver-dispatch table to system virtual addresses 

• Calls the controller-initialization routine 

Chapter 14 contains detailed descriptions of all SYSGEN 
commands related to device drivers. 


13.1.2 Initialization During Recovery From a Power Failure 

During powerfail-recovery procedures, the operating system 
locates every unit-control block in the I/O database. Each unit- 
control block points to a channel-request block for the device's 
controller. The channel-request block contains the address 
of the controller initialization routine, if one was specified. 

The system uses the following chain of pointers to locate the 
address of the initialization routine: 

DDB —> UCB —> CRB —> controller initialization routine 


If an invocation of the DPT_STORE macro loaded the 
address of a controller-initialization routine into the CRB$L_ 
INTD+VEC$D_INITIAL field of the channel-request block, 
the operating system calls that initialization routine for each 
controller. 

Next, the system checks for a unit-initialization routine. First, 
the system examines the unit-initialization field in the driver- 
dispatch table (DDT$L_UNITINIT). If the field does not contain 
an address, the system checks the channel-request block using 
the following chain of pointers: 

DDB —> UCB --> CRB —> device unit initialization routine 


MASSBUS drivers store unit-initialization routines addresses 
only in the driver-dispatch table. 
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If either the channel-request block or the driver-dispatch table 
contains a nonzero address for such a routine, the system calls 
the routine to initialize the device unit. The system calls only 
one routine; if the driver-dispatch table contains an address, the 
address in the CRB is ignored. 


13.1.3 Initialization Context 

The VAX/VMS operating system always calls controller and 
unit initialization routines with IPL raised to IPL$__POWER. 
The high IPL prevents any interrupts from reaching the 
processor while initialization is occurring. The initialization 
routines must not lower IPL. The system calls initialization 
routines with a JSB instruction; the routines return by executing 
an RSB instruction. 

Controller initialization routines are device-dependent. For 
example, a controller-initialization routine for a card reader 
might enable interrupts from the device by setting the interrupt- 
enable bit in the device's control/status register. A disk's 
controller-initialization routine, on the other hand, might 
enable interrupts and initialize all unit-status registers. 

At the time of a call to a controller-initialization routine, the 
registers contain the following values: 


Register 

Value 

R4 

Address of the control/status register 

R5 

Address of the interrupt-data block that describes 
the controller 

R6 

Address of the device-data block associated with the 
controller 

R8 

Address of the channel-request block for the 
controller 


Unit-initialization routines are useful for initializing device¬ 
dependent fields in the unit-control block. For example, 
unit-initialization routines for disks can also set disk-drive 
parameters (such as number of cylinders) in the unit-control 
block and wait for online units to spin up to speed. Unit- 
initialization routines must set the online bit in the unit-control 
block (UCB$V_ONLINE) to declare the unit to be online. 
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If a device needs permanently allocated UNIBUS adapter 
resources, a unit-initialization routine can call VAX/VMS 
UNIBUS-adapter-resource-management routines to allocate 
the resources. Then, the initialization routine can set bits in 
the CRB'S UNIBUS-adapter-resource-description fields, for 
example, VEC$V_PATHLOCK in CRB$L_INTD+VEC$B_ 
DATAPATH. 

When a unit-initialization routine is called, the registers contain 
the following values: 


Register Value 

R3 Address of the primary control/status register 

R4 Address of the secondary control/status register; R4 

is equal to R3 if there is no secondary CSR 

R5 Address of the device's unit-control block 


If a driver's initialization routines modify R4 through Rll, the 
routines must save the contents of the registers before use and 
restore them before returning control to the operating system. 


13.2 Cancel-I/O Routine 

VAX/VMS routines call the cancel-I/O routine in a device 

driver under the following circumstances: 

• When a process issues a Cancel-I/O-on-Channel system 
service 

• When a process deallocates a device and no process I/O 
channels are assigned to the device 

• When a process deassigns a channel from a device 

• When the command interpreter performs cleanup operations 
as part of image termination by canceling all pending I/O 
requests for the image and closing all image-related files 
open on process I/O channels 

The VAX/VMS routine EXE$CANCEL locates the unit-control 

block for the device associated with a process I/O channel from 

a pointer in the channel-request block, as follows: 

channel index number --> CCB --> UCB address 
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EXE$CANCEL takes the following steps: 

1 Raises IPL to fork level 

2 Removes from the device's pending-I/O queue all I/O- 
request packets associated with the process 

3 Sets the status code SS$_CANCEL in IRP$L_MEDIA 

4 For buffered-I/O-read operation, clears the buffered-read- 
function bit (IRP$V_FUNC) in IRP$W_STS 

5 Inserts the I/O-request packets removed from the pending- 
I/O queue into the I/O postprocessing queue 

6 If the I/O-postprocessing queue is empty, requests a 
software interrupt 

Then, EXE$CANCEL calls the cancel-I/O routine specified 

in the dispatch table of the associated device driver. 

EXE$CANCEL locates the routine using the following chain 

of pointers: 

UCB —> DDT —> address of the cancel-I/O routine 


The cancel-I/O routine gives the driver an opportunity to 
prevent further device-specific processing of the I/O request 
currently being processed on the device. 


13.2.1 Context of a Cancel-I/O Routine 

When EXE$CANCEL calls the cancel-I/O routine, IPL is at 
driver fork IPL so that the routine can read and modify the 
device's unit-control block. Registers at the time of the call 
contain the following values: 
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Register 

Value 


R2 

Channel index number 


R3 

Address of the current l/O-request packet 

R4 

Address of the process-control block of the process 
for which the cancel-I/O on Channel system service 
is being performed 

R5 

Address of the device's unit-control block 

R8 

Reason for the call to cancel the I/O request. Codes 
that signify the reasons for cancellation are defined 
by the $CANDEF macro. Possible values for R8 
include: 


CAN$C_CANCEL 

Called by SCANCEL or 
$DALLOC system services 


CAN$C_DASSGN 

Called by SDASSGN system 
service 


If a cancel-I/O routine uses registers other than RO through R3, 
it must save the registers and restore them before exiting. 

Device drivers might want to base their cancel-I/O operation 
on whether the cancel-I/O request is the result of a channel 
deassignment (CAN$__DASSGN). For example, the terminal 
driver cancels out-of-band-AST requests only if the call to 
its cancel-I/O routine results from a Deassign-I/O-Channel 
($DASSGN) system service call. 


13.2.2 Drivers That Need No Cancel-I/O Routine 

Some devices do not need any device-dependent processing 
performed for an I/O request; you can omit the CANCEL 
argument from the DDTAB macro. In this case, the DDTAB 
macro expansion loads the address of the VAX/VMS routine 
IOC$RETURN into the appropriate position in the driver- 
dispatch table. The routine IOC$RETURN executes a single 
RSB instruction. 
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13.2.3 Device-Independent Cancel-I/O Routine 

Drivers can specify the VAX/VMS routine IOC$CANCELIO 
as the value of the CANCEL argument in the DDTAB macro 
invocation. IOC$CANCELIO cancels I/O to a device in the 
following device-independent manner: 

1 It confirms that the device is busy by examining the device¬ 
busy bit in the UCB status word (UCB$V_BSY in 
UCB$W_STS). 

2 It locates the process-identification field in the I/O-request 
packet currently being processed on the device by using the 
following chain of pointers: 

UCB --> IRP --> process identification field 

IOCSCANCELIO confirms that the field (IRP$U_PID) 
contains the same value as the corresponding field in the 
process-control block (PCB$L_PIP). 

3 It confirms that the specified channel-index number is 
the same as the value stored in the I/O-request packet's 
channel-index field (IRP$W_CHAN). 

4 It sets the cancel-I/O bit in the UCB status word (UCB$V_ 
CANCEL in UCB$W_STS). 

Other driver routines, such as the device-timeout routine, 
check the cancel-I/O bit to determine whether to retry the I/O 
operation or abort it. 


13.2.4 Device-Dependent Cancel-I/O Routines 

Drivers that include their own cancel-I/O routines must 
perform the first three steps of IOC$CANCELIO listed in 
Section 13.2.3 to determine whether the I/O request being 
processed originates from the process canceling I/O on a 
channel. If the three checks succeed, the cancel routine can 
proceed in a device-specific manner. 
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13.3 Error-Logging Routines 

The operating system supplies two routines that drivers can call 
to allocate and fill error-logging buffers after a device error or 
timeout occurs: 

• ERL$DEVICERR 

• ERL$DEVICTMO 

Both routines expect to find the address of the device's unit- 
control block in R5. Drivers must call them at fork IPL. Each 
routine performs the following steps: 

1 It allocates an error log buffer of the length specified in the 
device's driver-dispatch table. It uses the following chain of 
pointers to locate the buffer length: 

UCB —> DDT —> length of error log buffer 

2 It loads into the buffer fields from the unit-control block, the 
I/O-request packet, and the device-data block. 

3 It loads the address of the location in the error-message 
buffer in which device-register's contents are to be stored. 

4 It calls a register-dumping routine in the device driver. It 
locates the routine using the following chain of pointers: 

UCB —> DDT —> register dump routine address 


Specify the address of a register-dumping routine with the value 
of the REGDMP argument to the DDTAB macro invocation. 

The register-dumping routine can expect the following registers 
to be loaded: 


Register Content 

RO Address of the buffer 

R4 Address of the control/status register if the driver 

used the WFIKPCH macro to wait for an interrupt or 
timeout 

R5 Address of the device's unit-control block 


The register-dumping routine should save and restore R3 
through Rll if the routine requires their use. 
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The driver register-dumping routine should fill the buffer as 
follows: 

1 Write a longword value representing the number of device 
registers to be written into the buffer 

2 Move device register longword values into the buffer 
following the register count longword 

The routine must store the contents of each device register to be 
logged in a longword in the buffer. For example, the following 
instruction stores the contents of the device register: 

MOVZWL##TD_STATUS(R4).(R0)+ 

A driver that supports error logging must satisfy the following 
prerequisites: 

• It must use the error-log extension of the unit-control block. 


• It must ensure that DDT$W_ERRORBUF is large enough to 
accommodate EMB$L_DV_REGSAV+4 plus one longword 
for each register to be dumped 

• Its driver-prologue table must set the device characteristic 
DEV$V_ELG in UCB$L_DEVCHAR. 
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You can load a user-written device driver any time after the 
system is bootstrapped. If the driver contains an error and the 
error does not crash or corrupt the operating system, you can 
correct the error and reload a new version of the driver. 


14.1 Preparation for Loading 

To prepare a device driver for loading, take the following steps: 

1 Write the device driver in one or more source files. If the 
driver comprises several source files, you must insert a 
.PSECT directive before any generated code in all files 
except the file that contains the DPTAB and DDTAB macro 
invocations. The following .PSECT must be used: 

.PSECT $$$115_DRIVER 

If a single source file contains the driver, you must not 
specify any .PSECT directives. The declaration of the 
DPTAB and DDTAB macros establish driver program 
sections correctly. 

2 Assemble the source file(s) with the system's macro library 
(SYS$LIBRARY:LIB.MLB). For example: 

$ MACRO MYDRIVER.MAR+SYS$LIBRARY:LIB.MLB/LIBRARY 

3 Link the object file with the VAX/VMS global symbol table, 
which is located in SYS$SYSTEM and called SYS.STB. If 
the driver consists of several source files, you must specify 
the file that contains the driver-prologue table as the first 
file in the list. The linker-options file must contain a BASE 
statement specifying a zero base for the executable image. 
The following is an example of the creation of the options 
file and the LINK command used to link a driver: 
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$ CREATE MYDRIVER.OPT 

BASE=0 

ICTRL/Zl 

$ LINK /NOTRACE MYDRIVER1[,MYDRIVER2_],- 

MYDRIVER.OPT/OPTIONS,- 

SYSSSYSTEM:SYS.STB/SELECTIVE_SEARCH 

The resulting image must consist of a single image section. 
The linker will report that the image has no transfer address. 


14.2 Loading the Driver 

Once the driver has been linked correctly, it is ready to be 
loaded. To load the driver into system virtual memory, run 
the System Generation Utility (SYSGEN) from the system 
manager's account or from an account having Change-Mode-to- 
Kemel privilege using the following command: 

$ RUN SYSSSYSTEM:SYSGEN 

SYSGEN responds with a prompt and waits for further input: 
SYSGEN> 

The VAX/VMS Utilities Reference Manual describes the full set 
of SYSGEN commands. The sections that follow describe those 
commands SYSGEN uses to load drivers: 

• LOAD (requires Change-Mode-to-Kernel (CMKRNL) 
privilege) 

• CONNECT (requires CMKRNL privilege) 

• RELOAD (requires CMKRNL privilege) 

• SHOW/ADAPTER (requires CMEXEC privilege) 

• SHOW/CONFIGURATION (requires CMEXEC privilege) 

• SHOW/DEVICE (requires CMEXEC privilege) 


In addition, you should understand SYSGEN's automatic 
configuration feature, as described in Section 14.3. 
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14.2.1 LOAD Command 

To load a device driver, issue the LOAD command. If the 
controller has only a single unit attached to it, issue the 
CONNECT command. 

Format 

LOAD driver-file-spec 

driver-file-spec 

The specification of the file containing the executable I/O driver 
to be loaded. The LOAD command obtains the driver's name 
from the DPT$T_NAME field in the driver-prologue table. If 
the name of the driver being loaded matches the name of any 
driver already in the configuration, the LOAD command will 
not load the driver. 

SYS$SYSTEM is the default device and directory name. EXE is 
the default file type. 

Description 

The driver-loading procedure compares the name in the 
prologue table of the driver being loaded with the name in 
the driver-prologue tables of the drivers already loaded into 
system memory. If no match is found, the procedure loads the 
new driver into contiguous locations in nonpaged pool and 
links the driver-prologue table into the system's linked list of 
DPTs. If the procedure finds a match, it takes no further action. 

Example 

SYSGEN> LOAD CRDRIVER 

This command loads the driver found in 
SYS$SYSTEM:CRDRIVER.EXE (the card-reader driver). 
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14.2.2 CONNECT Command 

The CONNECT command creates control blocks in the I/O 
database for devices. The CONNECT command can also load 
the driver if it has not been previously loaded into system 
memory. 

Format 

CONNECT device-name required-quals [optional-quals] 

Command Qualifiers 

/[NO]ADAPTER=nexus 

/CSR=csr-address 

/CSR_OFFSET=csr-offset 

/VECTOR=vector-address 

/VECTOR_OFFSET=vector-offset 

/DRIVERNAME=driver-name (optional) 

/NUMVEC=number (optional) 

/ADPUNIT=unit-number (optional) 

/MAXUNITS=number (optional) 

Parameter 

device-name 

The name of the device for which control blocks are to be 
added to the I/O database. Specify the device name in the 
following format: 

ddcu 

dd = device code (up to 9 alphabetic characters) 
c = controller designation (alphabetic) 

u = unit number 

For example, LPAO specifies the line printer (dev) on controller 
A (c) at unit 0 (u). When specifying the device name, do not 
follow it with a colon (:). 

The device code and controller specification must be a unique 
and accurate device name and controller combination. If 
control blocks for the specified device/controller already exist, 
the driver-loading procedure does not create any control blocks 
or perform any initialization operations. If the device/controller 
name does not accurately name a device, the procedure will 
create spurious control blocks. 
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Required Qualifiers 
/[NO]ADAPTER=nexus 

The nexus value of the UNIBUS adapter, MASSBUS adapter, or 
other controller to which the device unit is attached. The nexus 
can be a number or a generic name listed by the /ADAPTER 
qualifier to the SYSGEN command SHOW. See Section 14.2.4 
for a discussion of SHOW/ADAPTER. 

Specify a nexus number in the range 0 through 15. All numeric 
values are interpreted as decimal unless they are preceded by a 
radix descriptor (%0 or %X). 

Nexus values for VAX processors are listed below. 


Adapter 

VAX-11 

/730 

VAX-11 

/750 

VAX-11 

/780 

MicroVAX 1 

UNIBUS 

0 

3 

8 

3 

0 

1 

- 

9 

4 

- 

2 

- 

- 

5 

- 

3 

- 

- 

6 

- 

MASSBUS 

0 

- 

4 

8 

- 

1 

- 

5 

9 

- 

2 

- 

6 

10 

- 

3 

- 

- 

11 

- 


Issue the CONNECT command with the /NOADAPTER 
qualifier to connect drivers associated with software devices. 
The mailbox driver is an example of this type of driver. 

/CSR=csr-address 

The UNIBUS address of the control/status register for the 
device. All numeric values are interpreted as decimal unless 
they are preceded by a radix descriptor (%0 or %X). 

/CSR_OFFSET=csr-offset 

On multiple-device boards, specifies the offset from the CSR 
address of the board to the CSR address of the device. All 
numeric values are interpreted as decimal unless they are 
preceded by a radix descriptor (%0 or %X). 
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/VECTOR=vector-address 

The UNIBUS address of the interrupt vector for the device. 

All numeric values are interpreted as decimal unless they 
are preceded by a radix descriptor (%0 or %X). Section 
14.3 provides additional information on vector and CSR 
assignments. 

/V ECT O R_0 F FS ET=vector-off set 

For devices on multiple-device boards, specifies the offset from 
the interrupt vector of the board to the interrupt vector of the 
device being connected. All numeric values are interpreted as 
decimal unless they are preceded by a radix descriptor (%0 or 
%X). Section 14.3 provides additional information on vector 
and CSR assignments. 

Optional Qualifiers 
/NUMVEC=number 

The number of interrupt vectors for the device. If this qualifier 
is omitted, the number of vectors defaults to 1. The number 
specified by the /VECTOR qualifier is the address of the lowest 
vector. Vectors must be contiguous. 

/DRIVERNAME=driver-name 

The name of the driver that handles the device being connected. 
If this qualifier is omitted, CONNECT follows one of two 
procedures to supply a default name. If the device to be 
connected is the first unit on the controller, CONNECT 
concatenates the first two characters of the device code with 
"DRIVER/ for example, LPDRIVER. Otherwise, CONNECT 
obtains the driver name from the DDB$T_DRVNAME field in 
the controller's device-data block. 

Consult the SYSGEN device table in Section 14.3.2 for the 
driver names of the devices supported by VAX/VMS. 

/ADPUNIT=unit-number 

The unit number of a device on the MASSBUS adapter. The 
unit number for a disk drive is the number of the plug on the 
drive. For magnetic tape drives, the unit number corresponds 
to the tape controller's number. 

/MAXUNITS=number 

The maximum number of units attached to the controller. This 
number determines the size of the UCB list appended to the 
interrupt-dispatch block. If specified, this value overrides the 
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maximum number of units designated in the driver-prologue 
table. The maximum number of units is stored in the IDB field 
IDB$ W_UNITS. 

Description 

The I/O database contains a linked list of driver-prologue 
tables. The CONNECT command looks for a device driver by 
scanning the driver-prologue tables and comparing the DPT$T_ 
NAME field in each DPT with the specified or defaulted driver 
name. If no match is found, the driver-loading procedure loads 
the driver image SYS$SYSTEM:drivemame.EXE; see Section 
14.2.1. 

Then the loading procedure examines the I/O database for 
control blocks that support the specified device. The procedure 
creates the following control blocks if they do not exist: 

• Device-data block—The procedure creates a device-data 
block for the generic device-name/controller-string specified 
if such a device-data block does not exist. 

When the procedure creates a device-data block for a 
UNIBUS device, it also creates a channel-request block and 
an interrupt-dispatch block. 

• Unit-control block—The procedure creates a unit-control 
block if it has just created a device-data block or if a unit- 
control block for the specified device does not exist. If a 
unit-control block already exists, the procedure continues 
to execute but makes no more modifications to the I/O 
database. 

After creating the control blocks, the driver-loading procedure 
performs the following initialization operations: 

• Performs the initialization operations specified by the DPT_ 
STORE macros in the initialization and reinitialization 
portions of the driver-prologue table. 

• Relocates all addresses in the driver-dispatch table and 
function-decision table to absolute system virtual addresses. 

• Raises IPL to IPL$_POWER so that initialization is not 
interrupted. 

• If a new channel-request block was created, the procedure 
calls the controller-initialization routine (if one exists) 
specified by CRB$L_INTD+VEC$L_INITIAL. 
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• Calls the unit-initialization routine (if one exists) specified 
by DDT$L_UNITINIT. If the DDT does not contain the 
address of a unit-initialization routine, the procedure calls 
the unit initialization routine (if any) specified by CRB$L_ 
INTD+VEC$I^UNITINIT. 


You should specify CONNECT commands with extreme 
caution. The driver and database-loading procedure does 
little error checking. If you specify a vector that has already 
been defined, the procedure rejects the CONNECT command. 
However, if the CONNECT command specifies an incorrect 
CSR address, the I/O database is apt to become corrupted. The 
result is a system failure. 

If the CONNECT command specifies an existing controller and 
a new device unit, the procedure creates a unit-control block for 
the new unit and calls a unit-initialization routine for the unit. 

A CONNECT command that specifies a device name with a 
new controller causes the driver-loading procedure to create 
a device-data block, channel-request block, interrupt-dispatch 
block, and unit-control block, and to call controller-initialization 
and unit-initialization routines. 

Example 

SYSGEN> CONNECT LPAO /ADAPTER=UB0/CSR=*/.0777514/VECT0R=y.0200 

This command loads the driver LPDRIVER, if it is not already 
loaded, and creates the device database (DDB, CRB, IDB, and 
UCB) needed to describe LPAO. 


14.2.3 RELOAD Command 

The RELOAD command loads a driver and removes a 
previously loaded version of that driver. The RELOAD 
command provides all of the functions of LOAD, except that it 
loads the driver regardless of whether it is already loaded. 

If any of the units associated with the driver are busy, the 
driver cannot be reloaded; SYSGEN issues an error message. 

Format 

RELOAD driver-file-spec 
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driver-file-spec 

The specification of the file containing the image of the driver 
to be loaded. 

Description 

To reload the driver, the driver-loading procedure compares 
the name field in the driver-prologue table of the driver being 
loaded with the name field in the driver-prologue tables of 
drivers already loaded into system memory. If no match is 
found, RELOAD loads the driver as described in Section 14.2.1. 

If the procedure finds a match, it first confirms that the current 
driver can be replaced by the new driver in the following steps: 


• Confirms that the DPT$M_NOUNLOAD flag in the driver- 
prologue table of the current driver is not set 

• Calls the current driver's unloading routine, if one exists, 
and confirms that the returned status is a success code 

• Ensures that no devices that use the current driver are busy, 
as indicated by the UCB$V_BSY bit set in UCB$W_STS 

If these checks succeed, the procedure replaces the current 
driver with the new driver. 

The procedure loads the new driver into contiguous locations 
in nonpaged system memory and searches the I/O database 
for references to the driver. If any device-data block refers to 
the driver being reloaded, the procedure reinitializes fields of 
the control blocks according to the reinitialization instructions 
in the new driver-prologue table; Chapter 7 describes the 
reinitialization fields of the DPT. 

Fields that must be reinitialized when a driver is reloaded 
include those that contain relative addresses within the driver: 

• Addresses of the driver's interrupt-servicing routines 

• Addresses of the device's unit-initialization and controller- 
initialization routines 

• Address of the driver-dispatch table 
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Once the driver-loading procedure has reinitialized fields, it 
calls the driver's controller-initialization routine. (It does not 
call the unit initialization routine.) The procedure then removes 
the newly replaced driver from the DPT list and deallocates the 
nonpaged system space the old driver occupied. Finally, the 
loading procedure links the address of the new driver-prologue 
table to the DPT list. 

Use the RELOAD command only when all devices supported 
by the driver are inactive. The checks for activity made by the 
RELOAD command might not detect all device activity, and 
changing a driver while an I/O request is being processed will 
cause a system failure. 


14.2.4 SHOW/ADAPTER 

The SHOW /ADAPTER command displays a list of nexus values 
of adapters in the system configuration. Use of the SHOW 
/ADAPTER command requires Change-Mode-to-Executive 
(CMEXEC) privilege. 

Format 

SHOW/ADAPTER 

Description 

The SHOW/ADAPTER command displays nexus numbers and 
generic names of UNIBUS and MASSBUS adapters, memory 
controllers, and interconnection devices such as the DR32. 

Example 

SYSGEN> SHOW/ADAPTER 

CPU Type: 11/780 
Hardware Revision #96 

Nexus Generic Name or Description 

1 16K memory, non-interleaved 

4 UBO 

5 UB1 

8 MBO 

9 MB1 

This example shows a VAX-11/780 that uses one memory 
controller composed of 16K-bit chips, two UNIBUS adapters, 
and two MASSBUS adapters. 
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14.2.5 SHOW/CONFIGURATION 

The SHOW/CONFIGURATION command displays information 
about the system configuration. 

Format 

SHOW/CONFIGURATION [/ADAPTER=nexus] 

[/COMMAND_FILE] 

[/0UTPUT=file-spec] 


nexus 

The nexus value of the UNIBUS adapter, MASSBUS adapter, or 
other interconnect to be displayed. 

file-spec 

The file specification of an optional output file. 

Description 

The SHOW/CONFIGURATION command displays the 
device name, number of units, nexus number and type, and 
shows the CSR and vector addresses of devices connected or 
autoconfigured in the system. You can direct the display to an 
output file with the /OUTPUT qualifier. 

If you combine the /OUTPUT and /COMMAND-FILE 
qualifiers, SYSGEN places all the device data into the output 
file, a command file, as arguments to CONNECT commands. 

By executing the commands in this file, you can remove 
a device from floating address space without completely 
rejumpering the CSR and vector addresses of the remaining 
devices. See the VAX/VMS Utilities Reference Manual for more 
details. 
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Example 

SYSGEN> SHOW/CONFIGURATION/ADAPTER=UB1 


System CSR and Vectors on 14-JUN-1984 14:58:26.08 


Name: 

LPA 

Units: 

1 

Nexus:4 

(UBA) 

CSR 

777514 

Vectorl: 

200 

Vector2: 

000 

Name: 

DYA 

Units: 

2 

Nexus:4 

(UBA) 

CSR 

777170 

Vectorl: 

264 

Vector2: 

000 

Name: 

XMA 

Units: 

1 

Nexus:4 

(UBA) 

CSR 

760070 

Vectorl: 

300 

Vector2: 

304 

Name: 

XMB 

Units: 

1 

Nexus:4 

(UBA) 

CSR 

760100 

Vectorl: 

310 

Vector2: 

314 

Name: 

XMC 

Units: 

1 

Nexus:4 

(UBA) 

CSR 

760110 

Vectorl: 

320 

Vector2: 

324 

Name: 

TTA 

Units: 

8 

Nexus:4 

(UBA) 

CSR 

760130 

Vectorl: 

330 

Vector2: 

334 

Name: 

TTB 

Units: 

8 

Nexus:4 

(UBA) 

CSR 

760140 

Vectorl: 

340 

Vector2: 

344 

Name: 

TTC 

Units: 

8 

Nexus:4 

(UBA) 

CSR 

760150 

Vectorl: 

350 

Vector2: 

354 

Name: 

TTD 

Units: 

8 

Nexus:4 

(UBA) 

CSR 

760160 

Vectorl: 

360 

Vector2: 

364 

Name: 

TTE 

Units: 

8 

Nexus:4 

(UBA) 

CSR 

760170 

Vectorl: 

370 

Vector2: 

374 


14.2.6 SHOW/DEVICE 

The SHOW/DEVICE command displays the location of a driver 
and the I/O database describing its devices in system virtual 
memory. This command requires Change-Mode-to-Executive 
(CMEXEC) privilege. 

Format 

SHOW/DEVICE [=driver-name] 

driver-name 

Name of the driver for which the information is to be displayed. 
If a driver name is not specified, the command displays 
information about all drivers and devices known to the system. 

Description 

The SHOW/DEVICE command displays the following 
information: 

• Name of the driver 

• The driver's starting and ending virtual addresses; the 
starting address is the address of the driver-prologue table 

• The generic device/controller name associated with the 
driver 

• The addresses of the device-data block, channel-request 
block, and interrupt-data block for the generic device 
/controller supported by the driver 
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• The unit numbers and UCB addresses for each device unit 
associated with the driver 

Example 

SYSGEN> SHOW/DEVICE=TMDRIVER 

_DRIVER_START_END_DEV_DDB_CRB_IDB_UNIT_UCB 

TMDRIVER 8009DF00 8009F020 

MTA 800BA660 800BA6C0 800BA360 

0 8009F020 
1 8009F0C0 


14.3 Autoconfiguration 

The standard VAX/VMS system start-up file runs SYSGEN 
to create and initialize an I/O database that describes all 
supported DIGITAL peripherals in the configuration. The 
following command requests SYSGEN to prepare a database for 
all supported DIGITAL devices attached to every UNIBUS and 
MASSBUS: 

SYSGEN> AUTOCONFIGURE ALL 

To configure devices attached to the UNIBUS, SYSGEN goes 
through the steps described in subsequent sections of this 
chapter. 

DIGITAL-supported devices are attached to the UNIBUS 
according to a table found in Appendix A of the PDP-11 
Peripherals Handbook. The basic rules follow: 

• A device of type A is always at a fixed and predefined 
CSR address; the device always interrupts at a fixed and 
predefined vector address; only one example of device A can 
be configured in each system. 

• A device of type B is identical to type A except that 
1 through n examples can be configured in a single 
system. Examples 2 through n are also located at fixed 
and predefined CSRs and vector addresses. 

• Devices of type C (1 through n of them) are always at fixed 
and predefined CSR addresses; however, the interrupt vector 
addresses vary according to what other devices are present 
on the system. 
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• Devices of type D (1 through n of them) are at CSR 
addresses and vector addresses that vary according to 
what other devices are present on the system. 

The CSR and vector addresses that vary are called floating 
addresses. The devices must be located in floating CSR and 
vector space according to the order in which the devices appear 
in the SYSGEN device table. This table, shown in Section 
14.3.2, lists all the type A and type B devices supported by 
VAX/VMS. It also lists the type C and type D devices that are 
recognized by SYSGEN's autoconfiguration procedure. 

The base of floating vector space is 300 8 . The base of floating 
CSR space is 760010 8 . 


14.3.1 The SYSGEN Autoconfiguration Facility 

The SYSGEN utility automatically configures a UNIBUS adapter 

as follows: 

• It initializes the base of floating space to 300 8 and 760010 8 
for vectors and CSRs, respectively. 

• It tests fixed and floating CSR address space for all known 
DIGITAL devices. 

• When a device is found at a CSR, SYSGEN reserves floating 
CSR and vector space for that device, if necessary. 

• It searches for the name of the driver associated with the 
device by checking the SYSGEN device table (shown in 
Section 14.3.2) and the directory SYS$SYSTEM. If the 
driver has already been loaded or exists as an image 
file in SYS$SYSTEM, SYSGEN creates and initializes 
the I/O database for that device and loads the driver's 
image if necessary. If the device at the CSR is supported 
by VAX/VMS and SYSGEN cannot locate its associated 
driver's image, it generates an error message. If the device 
is unsupported and has no corresponding driver's image, 
SYSGEN ignores the condition. 
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14.3.2 The SYSGEN Device Table 

The SYSGEN device table lists the characteristics of all 
DIGITAL devices. This table indicates the following 
information for each device type: 

• The device controller name 

• The name of the device driver, and whether it is supported 

• The name of the device recognized by VAX/VMS 

• The interrupt vector 

• The number of interrupt vectors per controller 

• The address of the first device register for each controller 
recognized by SYSGEN (the first register is usually, but not 
always, the CSR) 

• The number of registers per controller 

Currently, the SYSGEN device table lists the devices in 
Table 14-1. 
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Table 14-1 SYSGEN Device Table 


Device 

Name 

Vector 

Number of 
Vectors 

Alignment 

Number of 

CSR/Rank Registers 

Driver 

Support 

CR 

CR11 

230 



777160 

CRDRIVER 

Yes 

DM 

RK611 

210 



777440 

DMDRIVER 

Yes 

LP 

LP11 

200 



777514 

LPDRIVER 

Yes 



170 



764004 





174 



764014 





270 



764024 





274 



764034 



DL 

RL11 

160 



774400 

DLDRIVER 

Yes 

MS 

TS11 

224 



772520 

TSDRIVER 

Yes 

DY 

RX211 

264 



777170 

DYDRIVER 

Yes 

« 

RB730 

250 



775606 

DQDRIVER 

Yes 

PU 

UDA 

154 



772150 

PUDRIVER 

Yes 

PT 

TU81 

260 



774500 

PUDRIVER 

Yes 

XE 

UNA 

120 



774510 

XEDRIVER 

Yes 

XQ 

QNA 

120 



774440 

XQDRIVER 

Yes 

OM 

DC11 

Float 

2 

8 

774000 

OMDRIVER 

No 






774010 








774020 








774030 








(maximum of 








32 units) 



DD 

TU58 

Float 

2 

8 

776500 

DDDRIVER 

Yes 


776510 

776520 

776530 


(maximum of 
16 units) 
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Table 14-1 

SYSGEN Device Table (Cont.) 



Device Name 

Number of Number of 

Vector Vectors Alignment CSR/Rank Registers 

Driver 

Support 


OB 


DN11 Float 1 


775200 

775210 

775220 

775230 


OBDRIVER No 


(maximum of 
16 units) 


YM DM1 IB Float 1 


770500 

770510 

770520 

770530 


YMDRIVER No 


(maximum of 
16 units) 


OA DR11C Float 


767600 

767570 

767520 

767550 


OADRIVER No 


(maximum of 
16 units) 


PR 


PR611 Float 1 


772600 

772604 

772610 

772614 


PRDRIVER No 


(maximum of 
8 units) 


PP 


PP611 Float 1 


772700 

772704 

772710 

772714 


PPDRIVER No 


(maximum of 
8 units) 
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Table 14-1 

SYSGEN Device Table (Cont.) 






Number of 


Number of 



Device 

Name 

Vector 

Vectors 

Alignment 

CSR/Rank Registers 

Driver 

Support 

OC 

DT11 

Float 

2 

8 

777420 

777422 

777424 

777426 

(maximum of 

8 units) 

OCDRIVER 

No 

OD 

DX11 

Float 

2 

8 

776200 

776240 

ODDRIVER 

No 

YL 

DL11C 

Float 

2 

8 

775610 

775620 

775630 

775640 

(maximum of 

31 units) 

YLDRIVER 

No 

YJ 

DJ11 

Float 

2 

8 

Float 4 

YJDRIVER 

No 

YH 

DH11 

Float 

2 

8 

Float 8 

YHDRIVER 

No 

OE 

GT40 

Float 

4 

8 

772000 

772010 

OEDRIVER 

No 

LS 

LPS11 

Float 

6 

8 

770400 

LSDRIVER 

No 

OR 

DQ11 

Float 

2 

8 

Float 4 

ORDRIVER 

No 

OF 

KW11W 

Float 

2 

8 

772400 

OFDRIVER 

No 

XU 

DU11 

Float 

2 

8 

Float 4 

XUDRIVER 

No 

XW 

DUP11 

Float 

2 

8 

Float 4 

OODRIVER 

No 

XV 

DV11 

Float 

3 

8 

775000 

775040 

775100 

775140 

XVDRIVER 

No 
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Table 14-1 SYSGEN Device Table (Cont.) 


Device 

Name 

Vector 

Number of 
Vectors 

Alignment 

CSR/Rank 

Number of 
Registers 

Driver 

Support 

OG 

LK11 

Float 

2 

8 

Float 

4 

OGDRIVER 

No 

XM 

DMC11 

Float 

2 

8 

Float 

4 

XMDRIVER 

Yes 

TT 

DZ11 

Float 

2 

8 

Float 

4 

DZDRIVER 

Yes 

XK 

KMC11 

Float 

2 

8 

Float 

4 

XKDRIVER 

No 

OH 

LPP11 

Float 

2 

8 

Float 

4 

OHDRIVER 

No 

01 

VMV21 

Float 

2 

8 

Float 

4 

OIDRIVER 

No 

OJ 

VMV31 

Float 

2 

8 

Float 

8 

OJDRIVER 

No 

OK 

DWR70 

Float 

2 

8 

Float 

4 

OKDRIVER 

No 

DL 

RL11 

Float 

1 

4 

Float 

4 

DLDRIVER 

Yes 

MS 

TS11 

Float 

1 

4 

772524 

772530 

772534 


TSDRIVER 

Yes 

LA 

LPA11 

Float 

2 

8 

770460 


LADRIVER 

Yes 

LA 

LPA11 

Float 

2 

8 

Float 

8 

LADRIVER 

Yes 

OL 

KW11C 

Float 

2 

8 

Float 

4 

OLDRIVER 

No 

RSV 

RSV 

Float 

1 

8 

Float 

4 

RSVDRIVER 

No 

DY 

RX211 

Float 

1 

4 

Float 

4 

DYDRIVER 

Yes 

XA 

DR11W 

Float 

1 

4 

Float 

4 

XADRIVER 

Yes 

XB 

DR11B 

124 



772410 


XBDRIVER 

No 

XB 

DR11B 

Float 

1 

4 

772430 

4 

XBDRIVER 

No 

XB 

DRUB 

Float 

1 

4 

Float 

4 

XBDRIVER 

No 

XD 

DMP11 

Float 

2 

8 

Float 

4 

XDDRIVER 

Yes 

ON 

DPV11 

Float 

2 

8 

Float 

4 

ONDRIVER 

No 

IS 

ISB11 

Float 

2 

8 

Float 

4 

ISDRIVER 

No 
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Table 14-1 SYSGEN Device Table (Cont.) 


Number of Number of 

Device Name Vector Vectors Alignment CSR/Rank Registers Driver Support 


XD 

DMV11 

Float 

2 

8 

Float 

8 

XDDRIVER 

No 

XE 

UNA 

Float 

1 

4 

Float 

4 

XEDRIVER 

No 

PU 

UDA 

Float 

1 

4 

Float 

2 

PUDRIVER 

Yes 

TX 

DMF32 

Float 

8 

4 

Float 

16 

YCDRIVER 

Yes 

XG 







XGDRIVER 

Yes 

LC 







LCDRIVER 

Yes 

XI 







XIDRIVER 

No 

XS 

KMS11 

Float 

3 

8 

Float 

8 

XSDRIVER 

No 

XP 

PCL11 

Float 

2 

8 

764200 


XPDRIVER 

No 






764240 









764300 









764340 




VB 

VS100 

Float 

1 

4 

Float 

8 

VBDRIVER 

No 

PT 

TU81 

Float 

1 

4 

Float 

2 

PUDRIVER 

Yes 

OQ 

KMV11 

Float 

2 

8 

Float 

8 

OQDRIVER 

No 

UK 

KCT32 

Float 

2 

8 

764400 


UKDRIVER 

No 






764440 









764500 









764540 




IX 

IEQ11 

Float 

2 

8 

764100 


IXDRIVER 

No 

TX 

DHV11 

Float 

2 

8 

Float 

8 

YFDRIVER 

Yes 

TX 

DMZ32/ 

Float 

6 

4 

Float 

16 

YCDRIVER 

Yes 


CPI32 








XG 

CPI32 

Float 

6 

4 

Float 

16 

XGDRIVER 

Yes 

DT 

TC11 

214 



777340 


DTDRIVER 

No 

VC 

VC01B 

060 



777200 


VCDRIVER 

Yes 



Devices not listed in the SYSGEN device table include: 


Non-DIGITAL-supplied devices with fixed CSR and 
vector addresses. These devices have no effect on 
autoconfiguration. Customer-built devices should be 
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assigned CSR and vector addresses beyond the floating 
address space reserved for DIGITAL-supplied devices. 

• Those DIGITAL-supplied, floating-vector devices that the 
AUTOCONFIGURE command does not recognize. Use the 
CONNECT command to attach these devices to the system. 


14.3.3 Device Driver Control of Autoconfiguration 

The SYSGEN autoconfiguration facility provides two features 
that drivers can use to control the automatic configuration of 
the devices they operate. These features are invoked through 
the DEFUNITS and DELIVER arguments to the DPTAB macro. 

The DEFUNITS argument to the DPTAB macro specifies a 
default number of units to be configured into the system. The 
DPTAB macro copies this value to the DPT$W_DEFUNITS field 
in the driver-prologue table. The SYSGEN autoconfiguration 
facility reads this field and creates unit-control blocks numbered 
zero through the default unit number minus one. The default 
value of DEFUNITS is one. 

The DELIVER argument to the DPTAB macro specifies the 
address of a driver-specific unit-delivery routine. An offset to 
this routine is stored in the DPT$W_DELIVER field within the 
driver-prologue table. When the DELIVER argument is present, 
the SYSGEN autoconfiguration facility calls the unit-delivery 
routine once for each unit, the number of which being specified 
in the DEFUNITS argument. 

The unit-delivery routine prevents the creation of unit-control 
blocks for devices that do not respond to a test for their 
presence. 

If the unit-delivery routine returns a true status in RO, the unit 
is configured. If the status in RO is false, the autoconfiguration 
facility does not configure the device. If the DELIVER argument 
is not used, the unit-delivery feature is disabled. 

SYSGEN calls the unit-delivery routine with a JSB instruction 
in the following context: 

• Interrupt priority level is at IPL$_POWER (31). 

• RO through R2 are available for use. 
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• R3 contains the address of the interrupt-dispatch block, of 
one exists. If none exists, the value contained in R3 is zero. 

• R4 contains the address of the control/status register for the 
controller. 

• R5 contains the number of the unit that the routine must 
decide whether or not to configure. 

• R6 contains the base address of UNIBUS adapter I/O space. 

• R7 contains the address of the configuration-control block 
(ACF). 

• R8 contains the address of the adapter-control block. 

The configuration-control block is described in Appendix A. 

The DZll's device driver specifies 8 as the default unit number, 
but no routine to configure eight terminal units automatically 
for each DZll's CSR. The RK611 device driver specifies 8 as 
the default number of units and also specifies the address of a 
unit-delivery routine that is called once for each of the eight 
possible devices on the controller. 


14.3.4 Floating-Vector Address Calculation 

To calculate the floating-vector address of a device, the 
SYSGEN utility rounds the current floating-vector base (CFVB) 
up to the next valid vector address boundary for the next device 
in the table. 

If a device is present, SYSGEN reserves floating-vector space 
for the device by computing a new CFVB: 

CFVB + (4 * number_of_vectors) ==> CFVB 


14-22 





Loading a Device Driver 


14.3.5 Floating-CSR Address Calculation 

To calculate the floating CSR address of a device, SYSGEN 
rounds the current floating CSR base (CFCB) up to the next 
valid floating CSR address. Floating CSR addresses must fall on 
an 8-byte boundary. 

SYSGEN tests the CSR address (CFCB) for the next device in 
the device table by executing a test word (TSTW) instruction 
on the address and noting whether there is a response at that 
address. 

If the device is present, SYSGEN reserves floating CSR address 
space for the device by computing a new CFCB: 

CFCB + bytes_in_register_set ==> CFCB 


When all devices of a particular type have been located and 
their floating CSR space reserved, SYSGEN reserves an extra 
block of CSR space to indicate a change to a new device type: 

CFCB + 8 ==> CFCB 


If the device is not present, SYSGEN reserves an extra block of 
CSR space to indicate a change to a new device type by adding 
eight to the rounded CFCB: 

CFCB + 8 ==> CFCB 


14.3.6 Rules for Configuration 

The formulas described in Sections 14.3.4 and 14.3.5 reduce to 

the following maxims: 

• Devices with fixed CSR addresses and fixed vector addresses 
must be attached according to the SYSGEN device table 
settings. 

• Devices with floating CSR or vector addresses must be 
attached in the order in which they are listed in the 
SYSGEN device table. 

• An 8-byte gap must be reserved between each different type 
of device that is located in floating CSR address space. 

• An 8-byte gap must be reserved in floating CSR address 
space for each device type that has no controller in its 
configuration. 
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14 . 3.7 


• An extra 8-byte gap must be reserved between the KW11C 
and the RX11 in floating CSR address space. 

When assigning floating vector addresses and registers to 
devices not supplied by DIGITAL, be sure to leave a generous 
gap between these addresses and those of DIGITAL devices 
because subsequent VAX/VMS maintenance updates might add 
new devices to the SYSGEN device table. 


Example of a UNIBUS Configuration 

This example shows the correct configuration for UNIBUS 
devices with floating CSR and vector addresses. Controllers 
flagged with an asterisk (*) are not supported by DIGITAL. 


Controller 

Vector(s) 

CSR (first register) 

1 DN11* 

300 

775200 

1 DU11* 

310 

760040 

1 DV11* 

320 

775000 

1 DMC11 

340 

760100 

2 DZIls 

350 

760120 


360 

760130 

2 TSIls 

224 

772520 


370 

772524 

3 DR1 IBs* 

124 

772410 (CSR is third register) 


400 

772430 


410 

760300 

1 customer 

420 

760320 

device 

(or higher) 

(or higher) 
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DELTA and XDELTA are debugging tools that can be used to 
monitor the execution of user programs and the VAX/VMS 
operating system. When you link DELTA with a user image 
that runs in a nonprivileged process, DELTA is a user-mode 
debugging tool. When run in a privileged process, however, 
DELTA acts as a multimode debugger; it allows you to debug in 
user mode or to change to kernel mode for debugging. DELTA 
does not support debugging at elevated IPLs. 

XDELTA is syntactically identical to DELTA but also allows you 
to debug code that executes at an elevated IPL. XDELTA is used 
for stand-alone debugging of driver code and the executive. 

In the command syntaxes and dialogues contained in this 
chapter, red ink indicates the commands typed by the user and 
black ink indicates the system prompts and responses. 


15.1 Bootstrapping the System with XDELTA 

Under VAX/VMS, drivers are part of the operating system. 

You normally bootstrap the system with two boot flags set 
to allow you to debug with XDELTA. One flag causes the 
bootstrapping procedure to include XDELTA in the system. The 
other boot flag indicates a stop at a breakpoint in VAX/VMS 
initialization. Execution of the breakpoint instruction causes 
control to transfer to a fault handler located in XDELTA. The 
procedures for bootstrapping the system with XDELTA differ 
depending on which processor the operating system is running. 
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15.1.1 Bootstrapping the System with XDELTA on a 

VAX-11/780 

In addition to the normal system bootstrap command files, the 
VAX/VMS console floppy diskette for a VAX-11/780 contains 
two command files that bootstrap the system with XDELTA: 

• DMAXDT 

• DBAXDT 

To bootstrap the system with XDELTA, follow the procedures 
in the Guide to VAX/VMS Software Installation with two 
exceptions: 

• Deposit the unit number of the device in R3. 

• Specify one of the command files listed above instead of the 
command files listed in the installation guide. 


The dialogue in Figure 15-1 is an example of bootstrapping the 
system with XDELTA on a VAX-11/780. 


Figure 15—1 Bootstrapping the System with XDELTA on a 

VAX-11/780 

»>DEP0SIT R3 0 

Deposit the unit number 0 in R3. 

»>®DMAXDT 

Boot the system from DMAO. The 
procedure boots the processor and 
prompts the user from SYSBOOT: 

SYSB00T> 

Enter any SYSBOOT command. If you 
did not set or load system parameters 
with the USE command, the system uses 
the parameters stored in the system 
image. To prevent the system from 
automatically rebooting after a 
bugcheck, you can set the system 
parameter BUGREBOOT to zero. 

SYSB00T> CONTINUE 

Continue with the bootstrapping 
operation. 
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15.1.2 Bootstrapping the System with XDELTA on a 
VAX-11/750 

If the VAX/VMS operating system is running on a VAX- 
11/750, you must issue the following command in order to 
bootstrap the system with XDELTA: 

»>B[/f] device-name 

Command Parameters and Qualifiers 
B 

The console BOOT command. See the Guide to VAX/VMS 
Software Installation for further details on this command. 

/f 

The 32-bit hexadecimal integer value loaded into R5 as an 
input value to VMB.EXE, the primary bootstrap program. The 
/f qualifier can have the following values: 


Value 

Meaning 

f=0 

Normal nonstop bootstrap (default) 

f=1 

Stop in SYSBOOT (equivalent to @DxyGEN on the 

VAX-11/780) 

f=2 

Include XDELTA with the system but do not take the 
initial breakpoint 

f=6 

Include XDELTA with the system and take the initial 
breakpoint 

f=7 

Include XDELTA with the system, stop in SYSBOOT 
and take the initial breakpoint at system initialization 
(equivalent to @DxyXDT on the VAX-11/780) 


device-name 

Indicates the name of the device that contains the volume to 
be bootstrapped. Specify the device name using the format 
ddcu (refer to the Guide to VAX/VMS Software Installation for 
a complete description of device name format). Both controller 
and unit identifiers must be specified; there are no defaults. If 
you do not use the device-name parameter, the /f qualifier is 
ignored. 

The dialogue in Figure 15-2 is an example of bootstrapping the 
operating system with XDELTA on a VAX-11/750. 
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Figure 15-2 Bootstrapping the System with XDELTA on a 

VAX-11/750 

»>B/7 DMAO 

Bootstrap the system from DMAO. The 
command boots the processor and 
prompts the user from SYSB00T. 

SYSB00T> 

Enter any SYSB00T commands. If you 
did not set or load system 
parameters with the USE command, the 
system uses the parameters stored in 
the system image. To prevent the 
system from automatically rebooting 
after a bugcheck, you can set the 
system parameter BUGREB00T to zero. 

SYSB00T> CONTINUE 

Continue with the boostrapping 
operation. 


To bootstrap the system from the console TU58, see the 
Guide to VAX/VMS Software Installation. The console TU58 
contains the command files DMAXDT and DBAXDT which 
are analogous to the files on the VAX-11/780 console floppy 
diskette. 


15.1.3 Bootstrapping the System with XDELTA on a 
VAX-11/730 

In addition to the normal system bootstrap command files, the 
VAX/VMS console DECtape for a VAX-11/730 contains two 
command files that bootstrap the system with XDELTA: 

• DQAXDT 

• DQOXDT 

To bootstrap a VAX-11/730 with XDELTA, follow the 
procedures outlined in the Guide to VAX/VMS Software 
Installation and specify one of the command files listed 
above. The dialogue in Figure 15-3 is a general example 
of boostrapping the system with XDELTA on a VAX-11/730. 

When the boot device is DQAO, you can omit the first step in 
Figure 15-3 and execute the command procedure DQOXDT: 
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Figure 15-3 Bootstrapping the System with XDELTA on a 

VAX-11/730 

»> 0DQ0XDT 


»>D/G/L 3 1 

Deposit the unit number 1 in R3 

»>®DQAXDT 

Boot the system from DQA1. The 
procedure boots the processor and 
prompts the user from SYSB00T: 

SYSB00T> 

Enter any SYSB00T command. If you 
did not set or load any system 
parameters with the USE command, the 
system uses the system parameters 
stored in the system image. To 
prevent the system from 
automatically rebooting after a 
bugcheck, you can set the system 
parameter BUGREBOOT to zero. 

SYSB00T> CONTINUE 

Continue with the bootstrapping 

operation. 


15.1.4 Proceeding from the Initial Breakpoint 

After being bootstrapped, the system displays its welcoming 
message and halts in XDELTA, as follows: 

1 BRK AT nmmnnim 
address/NOP 

XDELTA is waiting for input. (XDELTA never issues explicit 
prompts.) Usually, you proceed from this point with the 
following command: 

; P [RET| 

All of the XDELTA commands are described in Section 15.10 
and in the VAX/VMS Utilities Reference Volume. 

If the operating system halts with a fatal bugcheck, the system 
prints the bugcheck information on the console terminal. 
Then, because the system parameter BUGREBOOT was set to 
zero, XDELTA prompts. Bugcheck information consists of the 
following: 

• Type of bugcheck 

• Register values 
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• Dump of one or more stacks 

PC and stack content indicate how an experimental driver 
crashed the system. You can then examine the system state 
further by issuing XDELTA commands. 


15.2 Loading the Driver 

Once the system is running, you can log in to the system as the 
system manager and load the experimental driver. 

To load the driver, run SYSGEN and issue the appropriate 
LOAD and CONNECT commands. Figure 15-4 provides a 
sample dialogue. 

The first SHOW command in Figure 15-4 causes SYSGEN to 
display the location of the device driver in system memory. 

You then define the device to the operating system. The second 
SHOW command causes SYSGEN to display the driver's 
location and the addresses of the device's DDB, CRB, IDB, and 
UCB. 


Figure 15-4 Loading a Driver 


$ RUN SYSSSYSTEM:SYSGEN 

SYSGEN> LOAD DMAO:[YOUR.DIRECTORY]YRDRIVER.EXE 

SYSGEN> SHOW /DEVICE=YRDRIVER 

_Driver_Start_End_Dev_DDB_CRB_IDB_Unit_UCB_ 

YRDRIVER 80060E50 80061070 

SYSGEN> CONNECT YR /ADAP=3/VEC=y.0274/CSR=y.0776240 
SYSGEN> SHOW /DEVICE=YRDRIVER 

_Driver_Start_End_Dev_DDB_CRB_IDB_Unit_UCB_ 

YRDRIVER 80060E50 80061070 

YRA 8005FDC0 80060B70 8005FE00 

0 80060BB0 


SYSGEN> EXIT 
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15.3 Inserting Breakpoints in the Source Code 

The SYSGEN command CONNECT calls controller 
initialization and unit initialization routines. To begin 
debugging the driver, you should ensure that the kernel-mode 
debugging utility XDELTA gains control of the driver before 
these routines execute. This is accomplished by placing calls 
to the special system routine INI$BRK within the source code 
of either the controller or unit initialization routines. To call 
INI$BRK, give the following instruction: 

JSB G~INI$BRK 

The INI$BRK routine contains two instructions: 

BPT 

RSB 

When the processor executes the BPT instruction, XDELTA 
gains control and reports the address of the breakpoint: 

1 BRK AT nnnnnnnn 

You can use INI$BRK as a debugging tool and place calls to it 
within any part of the driver source code. 

To determine the last driver PC before the breakpoint, examine 
the kernel stack. The stack register is register RE (hexadecimal 
format): 

RE/address /address 

Display RE to find the ^address of the top of the stack. Another 
display command (/) reveals the contents of the top of the 
stack, which should be the return address to the driver that 
called INISBRK. 
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15.4 Calculating the Base of Driver Code 

Before you debug the driver, it is a good idea to calculate the 
base address of driver code, as follows: 

1 Run SYSGEN and issue the SHOW/DEVICE command. 

The resulting display lists the location in nonpaged pool at 
which SYSGEN loaded the driver. 

2 Consult the load-map for the driver (obtained at driver link 
time). The driver resides in two program sections (PSECTs): 

$$05_PROLOGUE driver-prologue table 

$$15_DRIVER driver code 

The locations given in the driver code listing are offsets 
from $$$115_DRIVER. Thus, you can calculate the base 
address of the driver by adding the address at which the 
driver was loaded to the offset associated with the PSECT 
$$$115_DRIVER shown in the map. 

If you do not have the load-map, consult the driver-prologue 
table in the driver listing. Look for the address of DPT_ 
STORE—END, which generates a 2-byte entry that terminates 
the DPT. To get the base address of driver code, add the 
address of DPT_STORE_END + 2 to the address at which the 
driver was loaded. You can set an XDELTA base register to the 
base of driver code; Section 15.7 describes this procedure. 



15.5 Requesting an XDELTA Software Interrupt 

Once the controller and unit initialization routines complete 
execution, you will need to set breakpoints in order to debug 
the driver. You can set a breakpoint in the driver source code 
by inserting calls to INI$BRK, as described in Section 15.3. You 
can also invoke XDELTA to set breakpoints interactively by 
requesting an XDELTA software interrupt. 


The procedures described in the following sections will issue 
a software interrupt to the processor at IPL 5. The IPL 5 
interrupt-servicing routine handles the interrupt by calling the 
routine INI$BRK, which in turn executes the first XDELTA 
breakpoint. XDELTA then issues this message: 


1 BRK AT nnnnnnnn 
addres8/N0P 


15-8 






Debugging a Device Driver 


15.5.1 Requesting an XDELTA Interrupt on a VAX—11 /780, 

VAX-11/782, or VAX-11/785 

To request an XDELTA software interrupt on a VAX-11/780, 
VAX-11/782, or VAX-11/785, issue the following commands 
at the console terminal: 

$ [CTRL/Pl 
»>HALT 

»>DEP0SIT/I 14 5 
»>CONTINUE 


15.5.2 Requesting an XDELTA Interrupt on a VAX—11 /750 

To request an XDELTA software interrupt on a VAX-11/750, 
issue the following commands at the console terminal: 

$ [CTRL/P | 

»>D/I 14 5 
»>C 

The VAX-11/750 accepts only one-character commands. 


15.5.3 Requesting an XDELTA Interrupt on a VAX—11 /730 
or 725 

To request an XDELTA interrupt on a VAX-11/730 or a VAX- 
11/725, issue the following commands at the console terminal: 

$ [CTRL/P| 

»>D/I 14 5 
»>C 


The VAX-11/730 and VAX-11/725 accept only one-character 
commands. 
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1 5.5.4 Requesting an XDELTA Interrupt on a MicroVAX I 

To request an XDELTA interrupt on a MicroVAX I system, press 
and release the HALT button on the CPU control panel, or, if it 
is enabled, press the BREAK key on the console terminal. Then 
issue the following commands at the console terminal: 

»>D/I 14 5 
»>C 


The MicroVAX I accepts only one-character commands. 


15.6 Looking at the Vector-Jump Table 

To gain familiarity with the I/O database, you might wish to 
look for the address of the location in the channel-request block 
that contains a JSB instruction to the driver's interrupt-servicing 
routine. You can do this at a controller initialization breakpoint 
because one of the inputs is the IDB address. The procedures 
for locating the driver interrupt-servicing routine on nondirect 
and direct vector UNIBUS adapters are shown below. 

Nondirect Vector Procedure 

R5/IDB-addre8S Q+10/ADP-address 
Q+10/vector-table-address 

Q+vector-address-in-hex/address-of-JSB-instruction-in-CRB 
Q! JSB-in8tmction 

Direct Vector Procedure 

R5/IDB-addres8 Q+10/ADP-address 
Q+10/vector-table-address 

Q+vector-address-in-hex+2/address-of-JSB-instruction-in-CRB 
Q!JSB-instruction 

Finding the address of the driver's interrupt-servicing routine 
at the expected vector does not guarantee that an interrupt 
from the device will dispatch to the driver's interrupt-servicing 
routine. If the device's physical vector is set to some other 
address, an interrupt from the device can dispatch to some 
other interrupt-servicing routine, or dispatch to an unassigned 
vector. 

See the SYSGEN device table shown in Chapter 14 for a list 
of vectors. Consult DIGITAL field service for help with any 
problem similar to the one described above. 
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15.7 Setting an XDELTA Base Register 

During a driver debugging session, you can use an XDELTA 
relocation register as a base from which to examine driver 
code and set breakpoints within the driver. Use one of the 
methods outlined in Section 15.4.2 to determine the base 
address of driver code, then set a relocation register by issuing 
the following command: 

driver-base-address,0;X 1 RET| 

This command sets relocation register XO to the base of driver 
code. Now you can examine offsets into the code using XO as a 
base: 

or 

XO + offset!instruction 


XDELTA also uses the base register to display address values in 
the base register plus offset format. Suppose, for example, that 
your driver contains the code shown below. 


50 

81 

90 

00D3 

132 10$: 

M0VB 

(R1)+.R0 


10 

13 

00D6 

133 

BEQL 

20$ 

20 

50 

91 

00D8 

134 

CMPB 

R0,#~A/ / 


F6 

19 

00DB 

135 

BLSS 

10$ 

8F 

50 

91 

00DD 

136 

CMPB 

R0,#~A/Z/ 


F0 

14 

00E1 

137 

BGTR 

10$ 

82 

50 

90 

00E3 

138 

MOVB 

R0.(R2)+ 


EB 

11 

00E6 

139 

BRB 

10$ 


If base register 0 contains the base address of your driver, the 
following XDELTA dialogue is possible: 


X0+D3,X0+E6!X0+D3/M0VB (R1)+,R0 
X0+D6/BEQL X0+E8 

X0+D8/CMPB RO,#20 

XO+DB/BLSS X0+D3 

XO+DD/CMPB RO.#7A 

X0+E1/BGTR X0+D3 

X0+E3/M0VB RO.(R2)+ 

X0+E6/BRB X0+D3 


To set breakpoints in driver code, give the command: 

XO + offset;B IRET1 
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To display a driver instruction and set a breakpoint, add the 
instruction's offset to the base register, for example: 

X0+1C!instruction .;B IRET| 

The last XDELTA command sets a breakpoint at the displayed 
location. See Section 15.10 or the VAX/VMS Utilities Reference 
Volume for a detailed discussion of XDELTA commands. 


15.8 Destroying Register Contents 

Because the driver frequently calls VAX/VMS I/O routines, 
you must be careful to anticipate the register usage of these 
routines. Most VAX/VMS common I/O support routines use 
R0 through R3 freely. A frequent driver bug is to load a value 
into R3 and expect to find it intact after a call to allocate or load 
UNIBUS adapter resources. 

Other VAX/VMS I/O routines write into R4. In some cases, the 
use of R4 is obvious; for example, IOC$REQSCHANL writes 
the device's CRB address into R4. In other cases, you might not 
anticipate the use of R4. 

For example, EXE$IOFORK saves the calling code's R4 in a 
fork block, and then writes the device's IPL into R4. Because 
the normal flow of events is that an interrupt-servicing routine 
restores a driver with a JSB instruction and the driver then calls 
EXE$IOFORK which returns to the interrupt-servicing routine, 
the instructions following the JSB in the interrupt-servicing 
routine can only assume R5 is still untouched. The coding 
sequence is as follows: 

MOVQ UCB$L_FR3(R5),R3 ; Restore R3-R4. 

JSB QUCB$L_FPC(R5) ; Restore the driver process. 


Between these instructions, the interrupt-servicing routine can 
make no assumptions about the contents of R0 through R4. 


POPR #M~<R0 I Rl,R2,R3.R4 f R5> ; Restore interrupt registers. 
REI ; Return from the interrupt. 
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15.9 Examining UCB, IRP, and PSL 

In addition to using XDELTA to debug drivers, you also 
can examine the contents of the unit-control block and the 
associated I/O-request packet. 

It also is useful to examine the contents of the PSL at the time 
of a system failure. The PSL, for example, indicates the IPL 
at the time. When the system fails it prints the PSL and other 
register contents on the console terminal. 

While the system is running, the following command can be 
used to examine the PSL in XDELTA: 

RF+4/ 

The PSL location is stored in the longword following the PC. 


15.10 XDELTA Commands 

Table 15-1 summarizes XDELTA commands. The sections that 
follow detail the commands. 


Table 15-1 XDELTA Command Summary 


Command 

Function 

/ 

! 

Open location (display contents in current mode) 

Open location (display contents as instructions) 


Close current location 

m 

Close current location; open next 

[tab] 

Open location specified by current value 

[esc! 

Display previous location 

= 

Display value of expression; set Q 

+ 

Add 

- 

Subtract 

space 

Add 

• 

Multiply 

@ 

Shift 

% 

Divide 
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Table 15-1 (Cont.) XDELTA Command Summary 

Command Function 

, Field separator 

Q Last quantity displayed 

Rn Register n 

Xn Base register n 

Pn Processor register n 

G Add ''X80000000 to subsequent or preceding value 

H Add ''X7FFE0000 to subsequent or preceding value 

Current location 

S Execute one instruction, step into subroutine call 

O Execute one instruction, step over subroutine call (on 

CALLx, JSB, or BSBx) 

;P Proceed from breakpoint 

;B Set/clear/display breakpoint 

;E Execute command string 

;G Go to location and proceed 

;X Set base register 

[B Set byte mode 

[W Set word mode 

[L Set longword mode 

[I Set instruction mode 

" Set ASCII mode 

'string 7 Deposit string at current location, autoincrementing 

dot. A single quote terminates a string; every 
RETURN and LINEFEED typed will be stored. 


1 5.10.1 Values and Expressions 

All numeric values are interpreted in hexadecimal radix. 
Expressions are strings of alternating values and binary 
operators, where the first and last items in the string are always 
values, as in the following example: 

G4A32 + 24 - . 


Trailing operators are ignored. 
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15.10.2 


Special Symbols 


XDELTA defines the following special symbols: 


Q 

X0-> XF 
R0-> RF 
P0-> Pnn 
RF+4 
G 

H 


Current location; set by slash (/), exclamation point 
(!) and TAB operations 

Last quantity displayed 

Base registers; used for remembering values 
General register names 
Internal processor registers 
PSL 

"X80000000; prefix for system space addresses; for 
example, G2E is equivalent to "X8000002E 

"X7FFE0000; prefix for control region prefix; for 
example, H2E is equivalent to "X7FFE002E 


15.10.3 Operators 

XDELTA recognizes the following operators: 

+ or space add 

- negate, subtract 

* multiply 

% divide 

@ shift (arithmetic) 

Evaluation of expressions is left to right with no precedence. 


15.10.4 Open and Display Value Command 
Syntax 

address-expression/old-value [new-value-expression] 


Type an address expression followed by a slash (/) character. 
XDELTA displays the contents of the location (old-value above) 
followed by a space character. You can change the value at the 
location by typing a new value and then pressing RETURN. If 
you press RETURN without preceding it with a value, the old 
contents remain unchanged. 
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15.10.5 


The display and the value deposited default to longword 
hexadecimal values. The length can be changed to byte or 
word with the set mode commands. 

A slash preceded by a null address expression uses the 
displayed value (Q) as the address value. This feature is 
convenient for following address linked chains. 

address-expression/old-value /old-value /old-value 


Display Instruction Command 
Syntax 

address-expression!decoded-instruction 


Type an address-expression followed by an exclamation point 
(!). XDELTA displays the contents of memory as a VAX/VMS 
MACRO instruction starting with the address you specify. 

XDELTA does not make any distinction between reasonable and 
unreasonable instructions or instruction streams; the decoding 
always begins at the specified address. The display instruction 
command does not allow you to modify the displayed location. 
The command sets a flag that causes subsequent close and 
display next or indirect location commands to perform 
instruction decoding. You can reset the flag with the open 
and display value command. 

Whenever an address appears as an instruction operand, 
XDELTA sets the last quantity displayed (Q) to that address. 
XDELTA changes Q only for operands that use program counter 
or branch displacement addressing modes; Q is not altered for 
literal and register addressing modes. This feature is useful for 
following branches, as shown below. 

address-expression!BRW address-2 !instruction-at-address-2 
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15.10.6 Close and Display Next Location Command 


Syntax 

m 


address/old-value 

Press LINE FEED. XDELTA closes the current open location, 
then opens and displays the value in the next location according 
to the current display mode. 

If instruction display is the current mode, XDELTA does not 
deposit a value in the open location. The next location is the 
first location after the instruction currently displayed. If value 
display is the current mode, you can deposit a value into the 
open location. In this case, the next location is the current 
location incremented by the current data width (byte, word, or 
longword). 


15.10.7 Display Range Command 
Syntax 



start-addr-expression,end-addr-expression/contents-of-start 


or 


start-addr-expression,end-addr-expression!contents-of-start 


Type two address expressions separated by a comma and 
followed by a slash (/) or exclamation point (!) character. 
XDELTA displays the range of addresses using the specified 
display mode (value or instruction). If you specify instruction 
display, XDELTA decodes one or more instructions. Otherwise, 
XDELTA displays the contents of each location in the current 
data type (byte, word, or longword). 
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15.10.8 

Indirect Command 

Syntax 

[TAB] 

address/old-value 

Press TAB. XDELTA uses the last quantity displayed (Q) as 
an address and displays that address and its contents using 
the current display mode. This command opens locations 
in the same way as the slash (/) and exclamation point (!) 
commands, but prints the information on a new line and 
displays the address value before showing the address's 
contents. 

15.10.9 

Display Previous Location Command 

Syntax 

[ESC] 

address/old-value 

Press ESC. Unless the current display mode is instruction, 
XDELTA decreases the location counter by the current data 
width, and displays the contents of the resulting location using 
the current data width and type. This command is ignored in 
instruction display mode. 

15.10.10 

Show Value Command 

Syntax 

expression=value-of-expression 

Type an expression followed by an equal sign (=). The 
expression can be composed of a series of values and operators 
from the set of operators listed in the command summary. 
XDELTA shows the value of the expression according to the 
current display data type. The last quantity (Q) is set to the 
value of the computed expression. 
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15.10.11 Step Instruction Command 

Syntax 

s 

Type an S. XDELTA causes one instruction to be executed, then 
displays the address of the next instruction and decodes that 
instruction. 

This command also sets a flag that causes subsequent close 
and display next or indirect location commands to perform 
instruction decoding. The open and display value command 
resets the flag. 

If the next instruction is BSBB, BSBW, JSB, CALLG, or CALLS, 
this command steps into the subroutine and displays the first 
instruction within the routine. 


15.10.12 Step Instruction Over Subroutine Command 

Syntax 

o 

Type an O. XDELTA causes one instruction to be executed, 
then displays the address of the next instruction and decodes 
that instruction. 

This command also sets a flag that causes subsequent close 
and display next or indirect location commands to perform 
instruction decoding. The open and display value command 
resets the flag. 

If the next instruction is BSBB, BSBW, JSB, CALLG or CALLS, 
XDELTA executes the entire subroutine and displays the 
instruction that immediately follows the subroutine call; this 
command steps over subroutines. 
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15.10.13 Setting Breakpoints 
Syntax 

address-expression;B 1 RET| 

Type an address followed by a semicolon (;) the letter B, then 
press RETURN. XDELTA sets a breakpoint at the specified 
location and assigns it the first available breakpoint number. 

Alternate syntax 

address-expression,n;B I RET| 


Type an address, followed by a comma, a single digit between 
2 and 8, a semicolon (;), the letter B, and then press RETURN. 
XDELTA sets a breakpoint at the specified location and assigns 
it the specified breakpoint number. Breakpoint 1 is reserved for 
INI$BRK. 

Before XDELTA executes the instruction as a breakpoint, 
it suspends normal instruction processing, sets a flag that 
causes subsequent close and display next or indirect location 
commands to perform instruction decoding, and displays the 
following message: 

n BRK at address 
address/decoded-instruction 

You can now enter XDELTA commands. You can reset the flag 
that controls instruction display mode by issuing the open and 
display value command. 


15.10.14 Clearing Breakpoints 
Syntax 

0,n;B fRETl 

Type zero (0), followed by a comma, a single digit between 2 
and 8, a semicolon (;), the letter B, and then press RETURN. 
XDELTA clears the specified breakpoint. Never clear 
breakpoint 1. 
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15.10.15 Displaying Breakpoint List 


Syntax 

;B [RET! 

Type a semicolon (;) followed by the letter B. XDELTA shows 
the current setting of all breakpoints. For each breakpoint, 
XDELTA displays the following information: 

• Breakpoint number 

• Address at which the breakpoint is set 

• Display address (for complex breakpoints; see Section 
15.10.19) 

• Command string address (for complex breakpoints) 


15.10.16 Setting Base Registers 



Syntax 

address-expression,n;X I RET1 


Type an expression followed by a comma (,), a single digit 
between 0 and D (hexadecimal), a semicolon (;), and the letter 
X. XDELTA assigns the specified expression to the base register 
selected by n. XDELTA confirms that the base register is set by 
displaying the value deposited in the base register. 

Whenever XDELTA displays an address closely located to an 
address stored in a base register, XDELTA displays the base 
register identifier (Xn) followed by an offset that gives the 
address's location in relation to the address stored in the base 
register. For example, if base register 2 contains 800D046A and 
the address XDELTA needs to display is 800D052E, XDELTA 
displays X2+C4. XDELTA computes relative addresses for 
opened or displayed locations and addresses that are instruction 
operands. 

XDELTA displays an address in base register plus offset 
format to a distance of 800 (hex) from the base register. If 
the address falls outside this range, XDELTA displays it as a 
hexadecimal value. Sections 15.10.22 and 15.10.23 describe 
several predefined base registers. 
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15.10.17 

Proceeding from Breakpoints 

Syntax 

;P [RETl 

Type a semicolon (; ) followed by the letter P and then press 
RETURN. XDELTA continues executing at the current PC. 

15.10.18 

Loading PC and Continuing 

Syntax 

addre88-expres8ion;G 1 RET| 

Type an address, a semicolon, and G, then press RETURN. 
XDELTA loads the address into PC and continues executing at 
the new PC. 

15.10.19 

Display Mode Control 

Syntax 

[B Byte width 

[W Word width 

[L Longword width 

[I Instruction display (using longword width) 

" ASCII display (using current width) 

Type a left square bracket ([) followed by one of the letters 

B, W, or L to change the current display width to byte, word, 
or longword respectively. The default value is longword. The 
setting remains in effect until another display mode control 
command is given. For example, the following command 
displays the least significant byte contained at the specified 
address and deposits the new value to that byte only. 

address-expression [B/ old-value new-value 

Type a left square bracket ([) followed by the letter I to 
change the current display mode to instruction format. This 
command is equivalent to the exclamation point (!) command 
and, similarly, is canceled by typing a slash (/) or a double 
quotation mark ( "). Instruction mode sets display mode storage 
units to longword values. For an example of instruction display, 
see Section 15.10.5. 
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You can display contents of memory locations in ASCII 
characters by typing an address expression followed by a 
double quotation mark ("). 

address-expression" old-value-in-ASCII 


Pressing LINE FEED displays the next location in ASCII. 

The display mode remains set to ASCII until the next slash (/) 
or exclamation point (!) command. At this point, the display 
mode reverts to hexadecimal. Width remains unchanged. 


15.10.20 The EXECUTE STRING Command 

Syntax 

address-expressioniE I RET| 

Type an address expression followed by a semicolon, the letter 
E, then press RETURN. This command executes the ASCII 
commands found at the specified address expression. If you 
terminate the ASCII commands with a semicolon followed by 
the letter P, XDELTA will proceed with program execution. If 
you terminate the string with null (1 byte of 0), XDELTA waits 
for a new command. 

To create command strings, open the address of the start of the 
string and deposit ASCII text as follows: 

address/old-contents 'XDELTA-command' I RET| 

You can use any XDELTA command, including RETURN, LINE 
FEED, and TAB. 

To terminate the string with a null, follow the above command 
with: 

./old-contents 0 I RET1 

You can deposit command strings into nonpaged system patch 
space. To determine the size of patch space and its starting 

address, locate the symbol PAT$A_NONPGD in the system 

map file (SYS$SYSTEM:SYS.MAP). This symbol contains a 
descriptor of the address and size of patch space remaining in 
the system, as shown below: 
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PAT$A_NONPGD:: 

.LONG size-in-bytes 

.LONG patch-space-start-address 

You can also preassemble command strings with your 
experimental driver. Locate the addresses of these strings 
as you would any other address within your driver. 


15.10.21 Setting Complex Breakpoints 
Syntax 

address-expression.n,display-addr-expression,command-string-address;B I RET1 

Type an address expression, followed by a comma, a single digit 
between 2 and 8, another address expression, and the address 
of a command string. The first address is the breakpoint 
address; the digit equals the breakpoint number. XDELTA 
shows the contents of the display address in the current display 
mode when the breakpoint is reached. The command string 
address specified in the last command parameter executes after 
automatic display. 


15.10.22 XDELTA Stored Commands 

XDELTA contains two predefined command strings whose 
addresses are contained in base registers XE and XF. You can 
use these commands during general system debugging as well 
as driver debugging; they perform the following functions: 

XE Use the value of base register XO as a page-frame number 
and display the PFN database for that page. 

XF Set base register XO to the value (PFN) in RO and perform 
the same function as XE. 

You must initialize the stored commands to set the relocation 
registers they use (X6-XD). Issue the following commands: 

XE;E [RET] 

XF;E I RET| 

Now you can use the stored commands to obtain the following 
information about a page-frame number: 

• Specified physical page number (PFN) 

• PFN state 
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• PFN type 

• PFN reference count 

• PFN backward link/working set list index 

• PFN forward link/share count 

• Page-table entry (PTE) pointer to PFN 

• PFN backing store address 

• Virtual block number in process swap image 


15.10.23 Stored Base Registers 

XDELTA defines two base registers useful in system debugging: 
X4 and X5. Base register X4 corresponds to the global symbol 
SCH$GL_CURPCB. This symbol contains the address of 
the current process's software process-control block (PCB). 

Base register X5 corresponds to the global symbol SCH$GL_ 
PCBVEC, which contains the starting address of the list of PCB 
slots. 


15.11 DELTA 

DELTA is a debugging tool that can be linked with a user 
program to examine that program's execution. To link and run 
DELTA, issue the following commands: 

$ LINK program-name 
$ DEFINE LIB$DEBUG SYS$LIBRARY:DELTA 
$ RUN/DEBUG program-name 


DELTA accepts all the XDELTA commands, plus two additional 
commands described in the following sections. 


15.11.1 The EXIT Command 
Syntax 

EXIT 1 RET| 

Typing EXIT causes DELTA to return control to the command 
interpreter. 
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15.11.2 Examining and Modifying Locations in Process 
Space 

Syntax 

process.id:address_expres8ion/old_contents 

DELTA displays the current contents at the specified address 
expression within the specified process. The modify flag 
controls the ability to modify locations opened by this 
command. To examine the flag, type: 

;M fRETl 

Modification access is inhibited by default (M=0). 

To open, examine, and change a location, type the commands: 
1; M fRETl 

process.id:address.expression/old.contents new_contents 


15.12 Guidelines for Debugging Device Drivers 

The following sections discuss errors commonly made 
during debugging sessions and describe additional debugging 
techniques. 


15.12.1 References to System Addresses 

References by drivers to system addresses within the executive 
must use general addressing (G~) mode. For example, use 

JSB G~INI$BRK 


15.12.2 Opening Device Registers in XDELTA 

References to 16-bit device registers must be word instructions; 
references to 8-bit device registers must be byte instructions. 
These restrictions apply to the XDELTA EXAMINE command; 
therefore, be sure to set the correct mode control before 
examining device registers. For example, if the address of 
the device CSR is in R4, give the following command: 

R4/c8r_addres8 [W/csr_contents 
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15.12.3 Incorrect References to Device Registers 

A common driver error is to access a nonexistent device 
register or to access the correct register with an instruction 
of incorrect word length. On VAX processors that use direct 
vector interrupts, these references cause a fatal machine 
check exception. On VAX processors using nondirect vector 
interrupts, these references cause a UNIBUS adapter error 
interrupt. The system logs the adapter error and continues. 
When debugging a device driver, it is a good idea to catch 
this type of driver error as early as possible. Set an XDELTA 
breakpoint at the place in the system where it detected a 
UNIBUS adapter error interrupt. Follow the steps outlined 
below: 

• Consult the system map file. Read the value of 
EXE$DW780_INT. 

• Enter XDELTA and set a breakpoint at the address of 
EXE$DW780_INT. When a UNIBUS adapter error interrupt 
occurs, XDELTA executes the breakpoint at EXE$DW780_ 
INT. 

• Examine the stack as follows: 

RE/current_stack_pointer/saved_R2 
saved_R3 
8aved_R4 
8aved_R5 
saved.PC 
saved.PSL 


LF 

LF^ 

iL 

LF 


In many cases, the saved PC on the stack is the address of the 
instruction that caused the error. In other cases (for example, 
when the offending instruction is executed at IPL 31), the saved 
PC is not the address of this instruction but an address some 
number of instructions later, when the system actually services 
the interrupt. 
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15.12.4 


XDELTA and System Failures 

Driver errors can cause the operating system to suspend activity 
in such a way that you cannot invoke XDELTA. In this case, 
the only recourse is to induce a system failure. Follow the 
procedure described in the VAX/VMS System Dump Analyzer 
Reference Manual ; the system will signal a fatal bugcheck. 

To gain control in XDELTA following a fatal bugcheck, 
stop in SYSBOOT while initializing the system and set the 
BUGREBOOT parameter to zero. The system will stop in 
XDELTA, thereby allowing you to examine the device unit- 
control block and other driver data to determine the driver 
error. 

Another, more thorough, way to determine the cause of a 
system failure is to leave the BUGREBOOT parameter set to 1, 
allow the system to reboot, and then invoke the System Dump 
Analyzer (SDA) to examine the condition of the I/O data 
structures at the time of the fatal bugcheck. The VAX/VMS 
System Dump Analyzer Reference Manual provides detailed 
information on fatal bugcheck stack format and how SDA can 
help debug a device driver. 
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The I/O Database 


The I/O database is a collection of control blocks allocated 
in nonpaged system memory. This database provides the 
following information: 

I/O-request packets describing in-progress I/O requests 

Device characteristics of each device type 

Number and type of each device unit 

Current activity on each device unit 

External entry points to all device drivers 

Entry points for controller and device unit initialization 
routines 

Interrupt vector dispatch code 
Addresses of device registers 
UNIBUS adapter's data path bit-map 


Much of this I/O database is created and used only by 
VAX/VMS routines. Other parts are the primary source of 
data for the device drivers. The sections that follow identify all 
I/O database's control blocks and describe their fields. Field 
descriptions are in the order in which they appear in the control 
blocks. 


Driver code must consider fields flagged with asterisks to be 
read-only fields. Fields marked by "spare" or "unused" are 
reserved for future use by DIGITAL unless otherwise specified. 
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A.1 Configuration-Control Block (ACF) 

The configuration-control block is used by the SYSGEN 
autoconfiguration facility to describe the device it is adding to 
the system. Device drivers can gain access to this data structure 
only if they have specified a unit-delivery routine in the driver- 
prologue table and only when that routine is executing. Under 
certain conditions, the information stored in the configuration- 
control block might be useful to a unit-delivery routine. 

The fields described in the configuration-control block are 
illustrated in Figure A-l and described in Table A-l. 

Figure A-1 Configuration-Control Block (ACF) 
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Table A-1 Contents of the Configuration-Control Block 


Field Name 

Contents 

ACF$I_ADAPTER* 

Address of the adapter-control block for the adapter 
currently being configured. 

ACF$I_CONFIGREG* 

Address of the configuration register for the adapter 
currently being configured. 

ACF$ W_A VECT OR* 

Offset from the base of the system-control block (SCB) 
to the interrupt vector of the adapter currently being 
configured 

ACF$B_AUNIT* 

Adapter unit number of the device or controller currently 
being configured 

ACF$B_AFLAG* 

Flags associated with the automatic configuration 

operation. Flags defined in this field include the following: 

ACF$V_RELOAD Reloading driver code 

ACF$V_CRBBLT CRB and IDB for this device 

are already built 

ACF$V_SCBVEC CVECTOR is an offset into the 

SCB 

ACF$V_NOLOAD_DB Do not load I/O database, only 

load driver 

ACF$V_SUPPORT VAX/VMS supported device 

ACF$V_GETDONE Addresses of data structures 

in the I/O database have been 
obtained 

ACF$I_CONTROLREG* 

Address of control/status for the controller currently 
being configured 

ACF$ W_C VECT OR* 

Offset in the adapter-control block's vector table to 
the longword that contains the transfer address of the 
interrupt vector used by the controller currently being 
configured (if ACF$V_SCBVEC is not set). If ACF$V_ 
SCBVEC is set, this field is the offset from the SCB base 
to the interrupt vector of the controller currently being 
configured. 

ACF$B_CUNIT* 

ACF$I_DEVNAME* 

Unit number of the device currently being configured. 

Address of a counted ASCII string that gives the name 
of the controller currently being configured. 

ACF$I_DRVNAME* 

Address of a counted ASCII string that gives the driver 
name for the controller currently being configured. 
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Table A-1 (Cont.) 

Contents of the Configuration-Control Block 

Field Name 

Contents 

ACF$W_MAXUNITS* 

Maximum number of units that can be connected to the 
controller currently being configured. 

ACF$B_NUMVEC* 

Number of interrupt vectors to configure for the controller 
currently being configured. 

ACF$B_COMBO_VEC* 

This field is called ACF$B_COMBO_VECTOR_OFFSET, 
and contains the offset to the vectors for a combo device 

ACF$B_COMBO_CSR* 

This field is called ACF$B_COMBO_CSR_OFFSET, and 
contains the offset to the start of the control registers of 
a combo device 

ACF$B_NUMUNIT* 

Number of units to be configured for the controller 
currently being configured. 

ACF$I_DLVR_SCRH 

Field available for use by the unit delivery routine. 
SYSGEN never alters this field. 


A.2 Adapter-Control Block (ADP) 

Each MASSBUS and UNIBUS adapter configured in the system 
is represented to VAX/VMS and driver routines by an adapter- 
control block. The adapter-control block stores adapter-specific 
static and dynamic data such as the adapter CSR address and 
mapping-register-wait queues. 

The fields of the ADP for a UNIBUS adapter are illustrated in 
Figure A-2 and described in Table A-2. 
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Figure A-2 Adapter-Control Block (ADP) 
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Table A—2 Contents of Adapter-Control Block 


Field Name 

Contents 

ADP$I_CSR* 

Virtual address of the adapter configuration 
register. The CPU initialization sets this field. 

The configuration register marks the base of 
adapter register space, an area that contains data 
path registers, mapping registers, or any other 
registers appropriate to the implementation of the 
adapter. 

ADP$I_LINK* 

Address of next ADP. The CPU initialization 
routine writes this field. A value of 0 indicates 
that this is the last ADP. 

ADP$W_SIZE* 

Size of the adapter-control block. The CPU 
initialization routine writes this field when the 
routine creates the ADP. For the UNIBUS adapter, 
this includes the UNIBUS-interrupt-servicing code 
and device vector table. 

ADP$B_TYPE* 

Type of control block. The CPU initialization 
routine writes the symbolic constant DYN$C_ADP 
into this field when the routine creates the ADP. 

ADP$B_NUMBER* 

Number of this type of adapter (for example, the 
number for a third MASSBUS adapter is 2). The 
CPU initialization routine writes this field when the 
routine creates the ADP. 

ADP$W_TR* 

Nexus number of the adapter. The CPU 
initialization routine writes this field when the 
routine creates the ADP. The driver-loading 
procedure compares the nexus number specified 
in a CONNECT command with this field of each 
ADP in the system to determine to which adapter 
a device is attached. 

ADP$W_ADPTYPE* 

Type of adapter. The CPU initialization routine 
writes the symbolic constant AT$_UBA into 
this field when the routine creates an ADP for a 
UNIBUS adapter. AT$_MBA is the type code for 
a MASSBUS adapter. 
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Table A-2 (Cont.) 

Contents of Adapter-Control Block 

Field Name 

Contents 

ADP$I_VECTOR* 

Address of vector table. The table is 512 bytes 
of longword vectors that correspond to UNIBUS 
device interrupt vectors (0-%O777). 

On VAX processors that handle direct vector 

interrupts, ADP$I_VECTOR points to the second 

(or third) page of the system-control block (SCB). 
The CPU uses this page when it dispatches the 
device interrupt to the driver interrupt-servicing 
routine. Each vector entry that corresponds 
to a vector in use contains the address of the 
controller's interrupt dispatcher (CRB$I—INTD). 

On VAX processors that handle nondirect vector 

interrupts, ADP$I_VECTOR points to a page 

allocated from nonpaged pool. Each longword 
in the page that corresponds to a vector in use 
contains the address of the controller's interrupt 
dispatcher (CRB$L_INTD+2). When the UNIBUS 
adapter interrupts on behalf of a UNIBUS device, 
the UNIBUS adapter interrupt-servicing routine 
saves RO through R5, determines the vector 
address of the interrupting device, indexes into 
the vector table, and executes the instruction at 
CRB$I_INTD+2. 

ADP$I_DPQFL* 

For both types of VAX processor, vector table 
entries that correspond to unused vectors contain 
the address of a UNIBUS adapter's unexpected- 
interrupt-servicing routine. 

Data path wait queue forward link. 
lOCSREQDATAP and IOC$RELDATAP read and 
write this field. When a driver fork process 
requests a buffered data path and none is 
currently available, IOC$REQDATAP saves driver 
context in the device's UCB fork block, inserts the 
fork block address in the data path wait queue, 
and suspends the driver fork process. 

When another driver calls IOC$RELDATAP to 
release a buffered data path, the routine dequeues 
a UCB fork block address from the data path wait 
queue, allocates a data path to the driver, and 
reactivates that driver fork process. 
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Table A-2 (Cont.) 

Contents of Adapter-Control Block 

Field Name 

Contents 

ADP$I_DPQBL* 

Data path wait queue backward link. 
IOC$REQDATAP and IOC$RELDATAP read and 
write this field. 

ADP$L_A VECTOR* 

ADP$I_BLONLY* 

ADP$I_MRQFL* 

Address of the first SCB vector for this adapter 

Reserved to DIGITAL 

Mapping-register-wait queue's forward link. 
IOC$REQMAPREG and IOCSRELMAPREG read and 
write these fields. When a driver fork process 
requests a set of mapping registers and the set 
is not currently available, IOC$REQMAPREG saves 
driver fork context in the device's UCB fork block, 
inserts the fork block address in the mapping- 
register-wait queue, and suspends the driver fork 
process. 

When another driver calls IOCSRELMAPREG to 
release a set of mapping registers, the routine 
dequeues a UCB fork block address from the 
mapping-register-wait queue, allocates the 
requested set of mapping registers to the driver, 
and reactivates that driver fork process. 

ADP$I_MRQBL* 

Mapping-register-wait queue's backward link. 
IOC$REQMAPREG and IOCSRELMAPREG read and 
write this field. 

ADP$I_INTD* 

Interrupt transfer vector. When a device attached 
to the UNIBUS adapter requests a hardware 
interrupt, the processor transfers control to the 

ADP$I_INTD field of the UNIBUS adapter's 

control block. The field contains code that 
dispatches the interrupt to the proper driver 
interrupt-servicing routine. The interrupt transfer 
vector is only used for UNIBUS adapters that 
directly generate interrupts. 

ADP$I_UBASCB* 

Series of four longwords that contain system- 
control-block-entry values, one for each bus 
request (BR) level or interrupt vector. The UNIBUS 
adapter power failure recovery procedure uses 
these values. 
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Table A-2 (Cont.) 

Contents of Adapter-Control Block 

Field Name 

Contents 

ADP$I_UCBSPTE* 

Page-table-entry values for the base of UNIBUS 
adapter register space and the base of UNIBUS 

I/O register space. These values are used during 
UNIBUS adapter power failure recovery. 

ADP$I_MRACTMDRS* 

The number of active mapping register descriptors 

in the arrays to which ADP$I_MRNREARY and 

ADP$I_MRFREGARY point. IOC$REQMAPREG 

and IOCSRELMAPREG use these fields when 
allocating and deallocating UNIBUS mapping 
registers. 

ADP$W_DPBITMAP* 

Data path allocation bit-map. IOC$REQDATAP 
and IOC$RELDATAP read and write this field. The 
CPU initialization routine sets the bit map to show 
as available all the buffered data paths supported 
by the UNIBUS adapter. 

The state of each of the available buffered data 
paths (whether in use or available) is recorded in 
the data path allocation bit map. One data path 
corresponds to each bit in the field. If a bit is 
clear, the related data path is currently allocated 
to a driver fork process. 

ADP$W_MRNFENCE* 

Contains negative one. This field acts as a 
boundary marker for the array specified by 

ADP$I_MRNREGARY. 

ADP$W_MRNREGARY* 

Mapping register "number of registers" array of 
124 words. The number of words, or cells, that 

are active in this array is contained in ADP$I_ 

MRACTMDRS. Each active cell gives a number 
of free mapping registers. For each active cell 
in this array, there is a corresponding first free 
mapping register number in the array specified by 
ADP$W_MRFREGARY. Together, these values 
give the base mapping register and number of 
free mapping registers for a block of free mapping 
registers. This information is used to allocate and 
deallocate UNIBUS mapping registers. 

ADP$W_MRFFENCE* 

Word that contains negative one. This field acts 
as a boundary marker for the array specified by 
ADP$W_MRFREGARY. 
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Table A-2 (Cont.) 

Contents of Adapter-Control Block 

Field Name 

Contents 

ADP$W_MRFREGARY* 

Mapping register "first register" array of 124 
words. The number of currently active cells in 

this array is contained in ADP$I_MRACTMDRS. 

Each active cell gives a number of the first free 
mapping register within a block of free mapping 
registers. For each active cell in this array, 
there is a corresponding cell in the number 
of registers array that gives a number of free 
mapping registers. Together, these values give 
the base mapping register and number of free 
mapping registers for a block of free mapping 
registers. This information is used to allocate and 
deallocate UNIBUS mapping registers. 

ADP$W_UMR_DIS* 

The number of disabled mapping registers. During 
system initialization, some mapping registers can 
be disabled so that their corresponding UNIBUS 
addresses can be accessed directly through 
backplane interconnect physical addresses. 




A.3 Channel-Control Block (CCB) 


When a process assigns an I/O channel to a device unit with 
the $ASSIGN, EXE$ASSIGN locates a free block among the 
process's preallocated channel-control blocks. EXE$ASSIGN 
then writes into the CCB a description of the device attached to 
the CCB's channel. 

The fields of a channel-control block are illustrated in 
Figure A-3 and described in Table A-3. 
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Figure A-3 Channel-Control Block (CCB) 
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Table A-3 Contents of Channel-Control Block 


Field Name 

Contents 

CCB$I_UCB* 

Address of the unit-control block of the assigned device 
unit. EXE$ASSIGN writes a value into this field. EXE$QIO 
reads this field to determine that the I/O request specifies a 
process I/O channel assigned to a device and to obtain the 
device's UCB address. 

CCB$I_WIND* 

Address of a window-control block (WCB) for a file- 
structured device assignment. This field is written by an 

ACP and read by EXE$QIO. 


A file-structured device's ACP creates a window-control 
block when a process accesses a file on a device assigned 
to a process channel. The window-control block maps 
the virtual block numbers of the file to a series of physical 
locations on the device. 

CCB$B_STS* 

Channel status. 

CCB$B_AMOD* 

Access mode plus 1 of the process at the time of the channel 
assignment. EXE$ASSIGN writes the process access mode 
value into this field. 

CCB$W_IOC* 

Number of outstanding I/O requests on the channel. 

EXE$QIO increases this field when it begins to process 
an I/O request that specifies the channel. During I/O 
postprocessing, the kernel-mode-AST routine decrements 
this field. Some FDT routines and EXE$DEASSIGN read this 
field. 

CCB$I_DIRP* 

Address of the l/O-request packet for the requested 
deaccess. A number of outstanding I/O requests can be 
pending on the same process I/O channel at one time. If 
the process that owns the channel issues an I/O request to 
deaccess the device, EXE$QIO holds the deaccess request 
until all other outstanding I/O requests are processed. 
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A.4 Channel-Request Block (CRB) 

The activity of each controller in a configuration is described in 
a channel-request block. This control block contains pointers 
to the wait queue of drivers ready to gain access to a device 
through the controller. It also stores the entry points to the 
driver's interrupt-servicing routines and device/controller 
initialization routines. 

The fields of the channel-request block are illustrated in 
Figure A-4 and described in Table A-4. 

Figure A—4 Channel-Request Block (CRB) 
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Table A-4 Contents of Channel-Request Block 


Field Name 

Contents 

CRBSI_WQFL* 

Controller data channel wait queue forward link. 
IOC$REQxCHANx and IOC$RELxCHAN insert and remove 
driver fork block addresses in this field. 

CRB$I_WQBL* 

A channel wait queue contains addresses of driver fork 
blocks that record the context of suspended drivers waiting 
to gain control of a controller data channel. If a channel 
is busy when a driver requests access to the channel, 
IOC$REQxCHANx suspends the driver by saving the driver's 
context in the device's UCB fork block and inserting the fork 
block address in the channel-wait queue. 

When a driver releases a channel because an I/O operation 
no longer needs the channel, IOC$RELxCHAN dequeues a 
driver fork block, allocates the channel to the driver, and 
reactivates the suspended driver fork process. If no drivers 
are awaiting the channel, IOC$RELxCHAN clears the channel 
busy bit. 

Controller channel wait queue backward link. 
IOC$REQxCHANx and IOC$RELxCHAN read and write 
this field. 

CRB$W_SIZE* 

Size of the CRB. The driver-loading procedure writes this 
field when the procedure creates the CRB. 

CRB$B_TVPE* 

Type of control block. The driver-loading procedure writes 
the symbolic constant DYN$C_CRB into this field when the 
procedure creates the CRB. 

CRB$B_TT_TYPE* 

CRB$W_REFC* 

The type of controller (DZ1 1 or DZ32) for terminals 

Unit-control block reference count. The driver-loading 
procedure increases the value in this field each time the 
procedure creates a UCB for a device attached to the 
controller. 

CRB$B_MASK* 

Mask that describes the status of the controller. At 
present, only one bit, CRB$V_BSY, is defined in this field. 
IOC$REQxCHANx reads the busy bit to determine whether 
the controller is free and sets this bit when it allocates the 
controller data channel to a driver. IOC$RELxCHAN clears 
the busy bit if no driver is waiting to acquire the channel. 
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Table A—4 (Cont.) Contents of Channel-Request Block 


Field Name 

Contents 

CRBSI_AUXSTRUC* 

Address of an auxiliary data structure that the device driver 
uses to store special controller information. A device 
driver that wishes to use this field can contain a controller 
initialization routine that allocates a block of nonpaged 
dynamic memory and sets this field to point to it. Use of 
this field is reserved to DIGITAL. 

CRB$I_TIMELINK* 

Forward link in a queue of channel-request blocks waiting 

for periodic wakeups. This field points to the CRB$I_ 

TIMELINK field of the next CRB in the list. The CRB$I_ 

TIMELINK field of the last CRB in the list contains zero. The 

listhead for this queue is IOC$GI_CRBTMOUT. Use of this 

field is reserved to DIGITAL. 

CRB$I_DUETIME* 

The time in seconds, relative to EXE$GI_ABSTIM, at which 

the next periodic wakeup associated with this channel- 
request block is to be delivered. Compute this value by 
raising IPL to IPL$_POWER, adding the desired number of 

seconds to the contents of EXE$GI_ABSTIM, and storing 

the result in this field. Use of this field is reserved to 
DIGITAL. 

CRB$I_TOUTROUT* 

The address of a routine to be called when the periodic 
wakeup associated with this CRB becomes due. The routine 

must compute and reset the value in CRB$I_DUETIME if 

another periodic wakeup request is desired. Use of this field 
is reserved to DIGITAL. 

CRB$I_LINK* 

Address of secondary CRB (for MASSBUS devices only). 
This field is written by the driver-loading procedure and read 
by lOCSREQSCHANx and IOC$RELSCHAN. 

CRB$I_INTD* 

Interrupt transfer vector. The driver-prologue table in every 
driver for an interrupting device specifies the address of 
a driver interrupt-servicing routine. The driver-loading 
procedure writes two instructions in this field: 

PUSHR #~M<RO , R1,R2,R3 . R4,R5> 

JSB @#~driver_isr_address 


Direct vector UNIBUS adapters transfer control to CRB$I_ 

INTD, which causes the processor to execute the PUSHR 
instruction to save RO through R5 on the stack. Next, the 
processor executes the JSB instruction to transfer control 
to the driver interrupt-servicing routine. 


A—14 








The I/O Database 


Table A-4 (Cont.) Contents of Channel-Request Block 


Field Name 

Contents 

CRB$I_INTD2* 

On nondirect vector UNIBUS adapters, the UNIBUS adapter 

interrupt-servicing routine transfers control to CRB$I_ 

INTD+2, which contains the JSB instruction to the driver 
interrupt-servicing routine. Because the UNIBUS adapter's 
interrupt-servicing routine has already saved RO through R5, 
the PUSHR instruction is bypassed. 

The CRB$I_INTD field is nine longwords long. Figure A-5 

and Table A-5 describe the contents of the rest of block. 

Second interrupt transfer vector for devices with multiple 
interrupt vectors. If the driver-prologue table in a device 
driver specifies the address of a second driver interrupt¬ 
servicing routine, the driver-loading procedure creates a CRB 
long enough to contain two INTDx fields of nine longwords 
each. 

The first two longwords of the CRB$I_INTD2 field contain 

a PUSHR and JSB instruction to the second driver interrupt¬ 
servicing routine. There are as many interrupt-transfer- 
vector blocks as there are device vectors. The number of 
device vectors is determined by the value specified in the 
/NUMVEC= qualifier to the SYSGEN command CONNECT. 


The interrupt-transfer-vector blocks contained in the CRB 
store executable code, driver entry points, and UNIBUS 
adapter information. The fields of the CRB$1__INTD block 
are illustrated in Figure A-5 and described in Table A-5. 
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Figure A-5 Contents of the Block to which CRB$I_IIMTD Points 
(VEC) 
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Table A-5 Fields of CRB$I—INTD 


Field Name Contents 

VEC$Q_DISPATCH* Contains the two interrupt dispatching instructions 

described above in the CRB$I_INTD field. This field is 

written by the driver-loading procedure. 

VEC$I_IDB* Address of the interrupt-dispatch block for the controller. 

The driver-loading procedure creates an IDB for each 
CRB and loads the address of the IDB in this field. 
Device drivers use the IDB address to obtain the virtual 
addresses of device registers. 

When a driver interrupt-servicing routine gains control, 
the top of the stack contains a pointer to this field. 

VEC$I_INITIAL* Address of the controller initialization routine. If a device 

controller requires initialization at driver-loading time and 
during recovery from a power failure, the driver specifies 
a value for this field in the driver-prologue table. 

The driver-loading procedure calls this routine each time 
the procedure loads the driver. The VAX/VMS powerfail 
recovery procedure also calls this routine to initialize a 
controller after a power failure. 
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Table A-5 (Cont.) 

Fields of CRB$I_IIMTD 

Field Name 

Contents 


VEC$W_MAPREG This field contains two fields, listed below. 


Field 

Contents 

VEC$V_MAPREG 

Number of the first UNIBUS 
adapter mapping register 
allocated to the driver that 
owns the controller data 
channel. 


IOC$REQMAPREG writes this 
field when the routine allocates 
a set of mapping registers to a 
driver fork process for a DMA 
transfer. IOC$RELMAPREG 
reads the field to deallocate a 
set of mapping registers. 


Device drivers read this field in 
calculating the starting address 
of a UNIBUS transfer. 

VEC$V_MAPLOCK 

If this bit is set, the mapping 
register set is permanently 
allocated. 


VEC$B_NUMREG Number of UNIBUS adapter mapping registers allocated 

to a driver. IOC$REQMAPREG writes this field when 
the routine allocates a set of mapping registers. 
IOC$RELMAPREG reads this field to deallocate a set 
of mapping registers. 
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Table A—5 (Cont.) 

Fields of CRB$I_IIMTD 

Field Name 

Contents 


VECSB—DAT APATH 

The data path specifier 
are used as follows: 

. The bits that make up this field 


0 -> 4 

The number of the data path 
used in a DMA transfer. The 
routine IOC$REQDATAP sets this 
field when a buffered data path 
is allocated and clears the field 
when the data path is released. 



The routine IOC$LOADUBAMAP 
copies the contents of this 
field into the UNIBUS adapter 
mapping registers. These bits 
also serve as implicit input to the 
IOC$PURGDATAP routine. 


VEC$V_LWAE 

Longword access enable (LWAE) 
bit. Drivers set this bit when 
they wish to limit the data path 
to longword-aligned, random- 
access mode. The routine 
IOC$LOADUBAMAP copies the 
value in this field to the UNIBUS 
adapter mapping registers. 


6 

Reserved to DIGITAL. 


VEC$V_PATHLOCK 

Buffered data path allocation 
indicator. Drivers set this bit to 
specify that the buffered data 
path is permanently allocated. 

VEC$I_ADP* 

Address of the UNIBUS adapter-control block (ADP). The 
SYSGEN command CONNECT must specify the nexus 
number of the UNIBUS adapter used by a controller. The 
driver-loading procedure writes the address of the ADP 
for the specified UBA into the VEC$I_ADP field. 


IOC$REQMAPREG and IOC$RELMAPREG read and write 
fields in the ADP to allocate and deallocate UNIBUS 
adapter mapping registers. 
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Table A—5 (Cont.) 

Fields of CRB$I_INTD 

Field Name 

Contents 

VEC$I_UNITINIT * 

Address of the device unit initialization routine. If a 
device unit requires initialization at driver-loading time and 
during recovery from a power failure, the driver specifies 
a value for this field in the driver-prologue table. 


The driver-loading procedure calls this routine for each 
device unit each time the procedure loads the driver. The 
VAX/VMS powerfail recovery procedure also calls this 
routine to initialize device units after a power failure. 


MASSBUS drivers that support mixed device types must 
not use this field. Instead, they should specify unit 

initialization in the (DDT$I_UNITINIT) unit initialization 

field of the driver-dispatch table. Other drivers can use 
either field. 


A.5 Device-Data Block (DDB) 

The device-data block is a variable-length block that identifies 
the generic device/controller name and driver name for a set 
of devices attached to a single controller. The driver-loading 
procedure creates a device-data block for each controller during 
autoconfiguration at system startup and dynamically creates 
additional device-data blocks for new controllers as they are 
added to the system using the SYSGEN command CONNECT. 
The procedure initializes all fields in the device-data block. All 
the device-data blocks in the I/O database are linked together 
in a single-linked list. The contents of IOC$Gl_DEVLIST 
points to the first entry in the list. 

VAX/VMS routines and device drivers refer to the device-data 
block. 

Fields of the device-data block are illustrated in Figure A-6 and 
described in Table A-6. 
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Figure A-6 Device-Data Block (DDB) 
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Table A-6 Contents of Device-Data Block 


Field Name 


Contents 


DDB$I_LINK* 

DDB$I_UCB* 

DDB$W_SIZE* 

DDB$B_TYPE* 

DDB$I_DDT 


Address of the next DDB. A zero indicates that this is the 
last DDB in the DDB chain. 

Address of the unit-control block for the first unit attached 
to the controller. 

Size of the DDB. 

Type of control block. The driver-loading procedure 
writes the constant DYN$C_DDB into this field when the 
procedure creates the DDB. 

Address of the driver-dispatch table. VAX/VMS can 
transfer control to a device driver only through addresses 
listed in the DDT, the CRB, and the UCB fork block. The 
driver-prologue table of every device driver must specify a 
value for this field. 
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Table A-6 (Cont.) 

Contents of Device-Data Block 

Field Name 

Contents 

DDBSl_ACPD 

Name of the default ACP for the controller. ACPs that 
control access to file-structured devices use the high-order 
byte of this field, DDB$B_ACPCLASS, to indicate the class 
of the file-structured device. If the SYSGEN parameter 
ACP_MULT is set to one, the initialization procedure 
creates a unique ACP for each class of file-structured 
device. 


Drivers initialize DDB$B_ACPCLASS by invoking a DPT_ 
STORE macro. Values for DDB$B_ACPCLASS are listed 
below. 


DDB$K_CART Cartridge disk pack 

DDB$K_PACK Standard disk pack 

DDB$K_SLOW Floppy disk 


DDB$K_TAPE Magnetic tape that simulates a file- 

structured device 

DDB$T_NAME* 

Generic name of the devices attached to the controller. 

The first byte of this field is the number of characters in 
the generic name. The remainder of the field consists of a 
string of up to 15 characters in length that, suffixed by a 
device unit number, identifies devices on the controller. 

DDB$T_DRVNAME* 

Name of the device driver for the controller. The first byte 
of this field is the number of characters in the driver name. 
The remainder of the field contains a string of up to 15 
characters in length taken from the driver-prologue table in 
the driver. 

DDBSl_SB* 

The address of the system block 

DDBSl_CONLINK* 

The next DDB in the connection subchain 

DDBSl_ALLOCLS* 

The allocation class of the device 

DDBSl_2P_UCB* 

The address of the first UCB on the secondary path. 
Another name for this field is DDBSl—DP_UCB. 


A.6 Driver-Dispatch Table (DDT) 

Each device driver contains a driver-dispatch table. The table 
lists entry points in the driver that various VAX/VMS routines 
call. An example is the entry point for the driver routine that 
starts an I/O operation on a device. 
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A device driver creates a driver-dispatch table by invoking the 
VAX/VMS macro DDTAB. The fields in the driver-dispatch 
table are illustrated in Figure A-7 and described in Table A-7. 

Figure A-7 Driver-Dispatch Table (DDT) 
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Table A-7 Contents of Driver-Dispatch Table 


Field Name Contents 

DDT$I_START Entry point to the driver start-l/O routine. Every driver 

must specify this field with the value of the START 
argument in the DDTAB macro invocation. 

When a device unit is idle and an I/O request is pending 
for that unit, IOC$INITIATE transfers control to the address 
contained in this field. 

DDT$I_UNSOLINT Entry point to the MASSBUS driver's unsolicited-interrupt¬ 

servicing routine. The driver specifies this field with the 
value of the UNSOLIC argument in the DDTAB macro 
invocation. 
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Table A—7 (Cont.) 

Contents of Driver-Dispatch Table 

Field Name 

Contents 

DDT$I_FDT 

This field contains the address of a routine that analyzes 
unexpected interrupts from a device. The standard 
interrupt-servicing routine, the address of which is stored 
in the CRB, determines whether an interrupt was solicited 
by a driver. If the interrupt is unsolicited, the interrupt¬ 
servicing routine can call the unsolicited-interrupt-servicing 
routine. 

Address of the driver's function-decision table. Every 
driver must specify this field with the value of the FUNCTB 
argument in the DDTAB macro invocation. 

EXESQIO refers to the FDT to validate 1/0-function codes, 
decide which functions are buffered, and call FDT routines 
associated with function codes. 

DDT$I_CANCEL 

Entry point to the driver cancel I/O routine. The driver 
specifies this field with the value of the CANCEL argument 
in the DDTAB macro invocation. 

DDT$I_REGDUMP 

Some devices require special clean-up processing when 
a process or a VAX/VMS routine cancels an I/O request 
before the I/O operation completes or when the last 
channel is deassigned. The SDASSGN, $DALLOC, and 
SCANCEL system services cancel I/O requests. 

Entry point to the driver register dump routine. The driver 
specifies this field with the value of the REGDMP argument 
in the DDTAB macro invocation. 

DDT$W_DIAGBUF 

IOC$DIAGBUFILL, ERL$DEVICERR, and ERL$DEVICTMO 
call the address contained in this field to write device 
register contents into a diagnostic or error-logging buffer. 

Size of the diagnostic buffer. The driver specifies this field 
with the value of the DIAGBF argument in the DDTAB 
macro invocation. The value is the size in bytes of a 
diagnostic buffer for the device. 

When EXE$QIO preprocesses an I/O request, the routine 
allocates a system buffer of the size recorded in this field 
if the user process has diagnostic privileges, specifies a 
diagnostic buffer in the I/O request, and this field of the 
DDT contains a nonzero value. IOCSDIAGBUFILL fills the 
buffer after the I/O operation completes. 
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Table A—7 (Cont.) 

Contents of Driver-Dispatch Table 

Field Name 

Contents 

DDT$W_ERRORBUF 

Size of the error log buffer. The driver specifies this 
field as the value of the ERLGBF argument in the DDTAB 
macro invocation. The value is the size in bytes of an 
error-logging buffer for the device. 

If error logging is enabled and an error occurs during 
an I/O operation, the driver calls ERL$DEVICERR or 
ERL$DEVICTMO to allocate and write error-logging 
data into the error message buffer. IOC$INITIATE and 
IOC$REQCOM write values into the error message buffer if 
an error has occurred. 

DDT$I_UNITINIT 

Address of the device unit initialization routine, if one 
exists. Drivers for MASSBUS devices use this field rather 

than CRB$I_INTD+VEC$I_UNITINIT. Drivers for UNIBUS 

devices can use either field. 

DDT$I_ALTST ART 

Address of the alternate start-l/0 routine. The VAX/VMS 
routine EXE$ALTQUEPKT initiates the alternate start-l/0 
routine at this address. 

DDT$I_MNTVER 

Address of the VAX/VMS routine IOC$MNTVER called at 
the beginning and end of a mount verification operation. 
The MNTVER argument to the DPTAB macro defaults to 
this routine. Use of the MNTVER argument to call any 
routine other than IOC$MNTVER is reserved to DIGITAL. 

DDT$I_CLONEDUCB 

DDT$W_FDTSIZE* 

The address of the routine to call when the UCB is cloned. 

The number of bytes in the function-decision table. 

The driver-loading procedure uses this field to relocate 
addresses in the FDT to system virtual addresses. 

DDT$I_MNTV_SSSC 

The address of the routine to call when performing mount 
verification for a shadow-set-state change. 

DDT$I_MNTV_FOR 

The address of the routine to call when performing mount 
verification for a foreign device. 

DDT$I_MNTV_SQD 

The address of the routine to call when performing mount 
verification for a sequential device. 


A.7 Driver-Prologue Table (DPT) 

When loading a device driver and its database into virtual 
memory, the driver-loading procedure finds the basic 
description of the driver and its device in a driver-prologue 
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table. This table provides the length, name, adapter type, and 
loading and reloading specifications for the driver. 

A device driver creates a driver-prologue table by invoking the 
VAX/VMS macros DPTAB and DPT_STORE. The fields of the 
DPT are illustrated in Figure A-8 and described in Table A-8. 

Figure A-8 Driver-Prologue Table (DPT) 


DPT$I_FLINK* 


DPT$I_BLINK* 


DPT$B_REFC* 

DPT$B_TYPE* 

DPT$W_SIZE 

DPT$W_UCBSIZE 

DPT$B_FLAGS 

DPT$B_ADPTYPE 

DPT$W_REINITTAB 

DPT$W_INITTAB 

DPT$W_MAXUNITS 

DPT$W_UNLOAD 

DPT$W_DEFUN ITS 

DPT$W_VERSION* 

DPT$W_VECTOR 

DPT$W_DELIVER 


DPT$T_NAME (12 bytes) 


DPT$Q_LINKTIME* 


DPT$I_ECOLEVEL* 


ZK-1785-84 


Table A-8 Contents of Driver-Prologue Table 


Field Name Contents 

DPT$I_FLINK* Forward link to the next DPT. The driver-loading procedure 

writes this field. The procedure links all driver-prologue 
tables in the system in a doubly linked list. 

DPT$I_BLINK* Backward link to the previous DPT. The driver-loading 

procedure writes this field. 


A—25 


























The I/O Database 


Table A—8 (Cont.) 

Contents of Driver-Prologue Table 

Field Name 

Contents 

DPT$W_SIZE 

Size in bytes of the device driver. The DPTAB macro 
writes this field by subtracting the address of the 
beginning of the DPT from the address specified as 
the END argument in the invocation of the DPTAB macro. 
The driver-loading procedure uses this value to determine 
the space needed in nonpaged system memory to load the 
driver. 

DPT$B_TYPE« 

Type of control block. The DPTAB macro always writes 
the symbolic constant, DYN$C_DPT, into this field. 

DPT$B_REFC* 

Number of device-data blocks that refer to this driver. The 
driver-loading procedure increments the value in this field 
each time the procedure creates another DDB that points 
to the driver's DDT. 

DPT$B_ADPTYPE 

Type of adapter used by devices driven by this driver. 
Every driver must specify the string "UBA" or "MBA" as 
value of the argument ADAPTER in the invocation of the 
DPTAB macro. The macro writes the value AT$_UBA or 
AT$_MBA in this field. 

DPT$B_FLAGS 

Driver loader flags. The driver can specify any of a set of 
flags as the value of the argument FLAGS in the invocation 
of the DPTAB macro. The driver-loading procedure 
modifies the loading and reloading algorithm followed on 
the basis of the settings of these flags. 

Flags defined in the flag field include the following: 
DPT$M_SUBCNTRL Device is a subcontroller 

DPT$M_SVP Device requires permanent 

system page; allocated during 
driver loading 

DPT$M_NOUNLOAD Driver cannot be reloaded 

DPT$V_SCS SCS code must be loaded with 

this driver 

DPT$W_UCBSIZE 

Size in bytes of unit-control blocks created for device units 
driven by this driver. Every driver must specify a value 
for this field as the value of the argument UCBSIZE in the 
invocation of the DPTAB macro. 

The driver-loading procedure allocates blocks of nonpaged 
system memory of the specified size when creating UCBs 
for devices associated with the driver. 
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Table A-8 (Cont.) 

Contents of Driver-Prologue Table 

Field Name 

Contents 


DPT$W_INITTAB Offset to driver-initialization table. Every driver must 

specify a list of control-block fields and values to be 
written into the fields at the time that the driver-loading 
procedure creates the control blocks. 

The driver invokes the VAX/VMS macro DPT_STORE to 
specify these fields and their values. Every driver must 
specify the following fields: 

UCB$B_FIPL Fork interrupt priority level 

UCB$B_DIPL Device interrupt priority level 


DPT$W_REINITT AB 


Other commonly initialized fields are: 


UCB$I_DEVCHAR 
UCB$B_DEVCLASS 
UCB$B_DEVTYPE 
UCB$W_DEVBUFSIZ 
UCB$I_DEVDEPEND 


Device characteristics 
Class of device 
Type of device 
Default buffer size 
Device-dependent parameters 


Offset to driver-reinitialization table. Every driver must 
specify a list of control-block fields and values to be 
written into fields at the time that the driver-loading 
procedure creates the control blocks or loads the driver. 


The driver invokes the VAX/VMS macro DPT_STORE to 
specify these fields and their values. Every driver must 
specify the following field: 

DDB$I_DDT Driver-dispatch table 


DPT$W_UNLOAD 


Other commonly initialized fields are: 

CRB$I_INTD+4 Interrupt-servicing routine 

CRB$I_INTD2+4 Second interrupt-servicing routine 

VEC$I_INITIAL Controller initialization routine 

VEC$I_UNITINIT Unit initialization routine 


Relative address of a driver action routine to be called 
when a driver is reloaded. The driver specifes this field 
with the value of the UNLOAD argument in the invocation 
of the macro DPTAB. 


A—27 





The I/O Database 


Table A-8 (Cont.) 

Contents of Driver-Prologue Table 

Field Name 

Contents 

DPT$W_MAXUNITS 

If the driver requires special clean-up processing such as 
buffer or mapping register deallocation before the driver 
can be reloaded, the driver must specify this field. The 
driver-loading procedure calls the driver unloading routine 
before reinitializing all device units associated with the 
driver. 

Maximum number of units on a controller that this driver 
supports. Specify this value in the MAXUNITS argument 
to the DPTAB macro. If no value is specified, the default 
is 8 units. 

DPT$W_VERSION* 

The version number that identifies the format of the driver- 
prologue table. The DPTAB macro automatically inserts a 
value in this field. SYSGEN checks its copy of the version 
number against the value stored in this field. If the values 
do not match, an error is generated. To correct the error, 
reassemble and relink the driver. 

DPT$W_DEFUNITS 

The number of unit-control blocks that the autoconfigure 
facility will automatically create. Drivers specify this 
number with the DEFUNITS arugment to the DPTAB 
macro. If the driver also gives a value to DPT$W_ 
DELIVER, this field is also the number of times that the 
autoconfiguration facility calls the unit delivery action 
routine. 

DPT$W_DELIVER 

Relative address of the device driver unit delivery routine 
that the autoconfiguration facility calls once for the number 
of unit-control blocks specified in DPT$W_DEFUNITS. The 
driver gives the relative address in the DELIVER argument 
to the DPTAB macro. 

DPT$ W_VECT OR 

Relative address of a driver-specific vector. Use of this 
field is reserved to DIGITAL. 

DPT$T_NAME 

Name of the device driver. Field is 12 bytes in length. One 
byte records the length of the name string; the name string 
can be up to 11 characters in length. Drivers specify this 
field as the value of the NAME argument in the invocation 
of the DPTAB macro. 

The driver-loading procedure compares the name of a 
driver to be loaded with the values in this field in all DPTs 
already loaded into system memory to ensure that it loads 
only one copy of a driver at a time. 
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Table A-8 (Cont.) 

Contents of Driver-Prologue Table 

Field Name 

Contents 

DPT$Q_LINKTIME* 

The time and date at which the driver was linked; taken 
from the image header. 

DPT$I_ECOLEVEL* 

The ECO level of the device driver; taken from the image 
header. 




A.8 Interrupt-Dispatch Block (IDB) 


The interrupt-dispatch block records controller characteristics. 
The driver-loading procedure creates and initializes this block 
when the procedure creates a channel-request block. The 
interrupt-dispatch block points to the physical controller by 
storing the virtual address of the control/status register. This 
register is the indirect pointer to all device unit registers. 

The fields of the interrupt-dispatch block are illustrated in 
Figure A-9 and detailed in Table A-9. 

Figure A-9 Interrupt-Dispatch Block (IDB) 
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Table A-9 Contents of Interrupt-Dispatch Block 


Field Name 

Contents 

IDBSl_CSR* 

Address of the control/status register (CSR). The 
SYSGEN command CONNECT must specify the address 
of a device's control/status register. The driver-loading 
procedure writes the system virtual equivalent of this 
address into the IDB$I_CSR field. 

Device drivers set and clear bits in device registers by 
referencing all device registers at fixed offsets from the 
CSR address. 

IDB$I_OWNER 

Address of the unit-control block of the device that owns 
the controller data channel. IOC$REQxCHANx writes a 
UCB address into this field when the routine allocates 
a controller data channel to a driver. IOC$RELxCHAN 
confirms that the proper driver fork process is releasing 
a channel by comparing the driver's UCB with the UCB 

stored in the IDB$I_OWNER field. If the UCB addresses 

are the same, IOC$RELxCHAN allocates the channel to 
a waiting driver by writing a new UCB address into the 
field. If no driver fork processes are waiting for the 
channel, IOC$RELxCHAN clears the field. 

IDB$W_SIZE* 

If the controller is a single-unit controller, the unit or 
controller initialization routine should write the UCB 
address of the single device into this field. 

Size of the IDB. The driver-loading procedure writes 
the constant IDB$K_LENGTH into this field when the 
procedure creates the IDB. 

IDB$B_TYPE* 

Type of control block. The driver-loading procedure 
writes the symbolic constant DYN$C_IDB into this field 
when the procedure creates the IDB. 

IDBSB—VECT OR* 

For UNIBUS devices, the interrupt vector number of the 
device right-shifted by 2 bits. SYSGEN writes a value 
to this field using either the autoconfiguration database 
or the value specified in the /VECTOR qualifier to the 
CONNECT command. Drivers for devices that define the 
interrupt vector address through a device register must 
use this field to load that register during unit initialization 
and reinitialization after a power failure. 

IDB$W_UNITS* 

Maximum number of units connected to the controller. 
The maximum number of units is specified in the driver- 
prologue table and can be overridden at driver-loading 
time. 
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Table A-9 (Cont.) Contents of Interrupt-Dispatch Block 


Field Name 

Contents 

IDB$B_TT_ENABLE* 

Reserved for use by the VAX/VMS terminal driver. 

IDB$B_COMBO_CSR» 

The name of this field is IDB$B_COMBO_CSR_OFFSET, 
and is abbreviated in order to allow representation of this 
field in this document. This field contains the address of 
the start of the CSRs for multicontroller devices (such as 
the DMF-32.) 

IDB$B_COMBO_VEC* 

The name of this field is IDB$B_COMBO_VECTOR_ 
OFFSET and is abbreviated in order to allow 
representation of this field in this document. This field 
contains the address of the start of the interrupt vectors 
for a multicontroller device. 

IDB$I_ADP* 

Address of the UNIBUS's adapter-control block (ADP). 
The SYSGEN command CONNECT must specify the 
nexus number of the UNIBUS adapter used by a device. 
The driver-loading procedure writes the address of the 

ADP for the specified UNIBUS adapter into the IDP$I_ 

ADP field. 

IDB$I_UCBLST* 

List of UCB addresses. The size of this field is the 
maximum number of units supported by the controller, 
as defined in the driver-prologue table. The maximum 
specified in the DPT can be overridden at driver load 
time. The driver-loading procedure writes a UCB address 
into this field every time the routine creates a new UCB 
associated with the controller. 


A.9 l/O-Request Packet (IRP) 

When a user process queues a valid I/O request by issuing a 
Queue-I/O-Request or Queue-I/O-Request-and-Wait system 
service, the service (EXE$QIO) creates an I/O-request packet. 
This packet contains a description of the request and receives 
the status of the I/O processing as it proceeds. 

The fields of an I/O-request packet are illustrated in 
Figure A-10 and detailed in Table A-10. 
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Figure A-10 l/O-Request Packet (IRP) 
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Table A-10 Contents of an l/O-Request Packet 


Field Name 

Contents 

IRP$I_IOQFL 

I/O queue forward link. EXESINSERTIRP reads and writes 
this field when the routine inserts I/O packets into a 
pending-1/0. IOC$REQCOM reads and writes this field 
when the routine dequeues I/O packets from a pending-l/O 
queue in order to send the packet to a device driver. 

IRP$I_IOQBL 

I/O queue backward link. EXE$INSERTIRP and 
IOC$REQCOM read and write these fields. 

IRP$W_SIZE* 

Size of the l/O-request packet. EXE$QIO writes the 
symbolic constant, IRP$C_LENGTH, into this field when 
the routine allocates and fills an l/O-request packet. 

IRP$B_TYPE* 

Type of control block. EXE$QIO writes the symbolic 
constant DYN$C_IRP into this field when the routine 
allocates and fills an l/O-request packet. 

IRP$B_RMOD* 

Access mode of the process at the time of the I/O 
request. EXE$QIO obtains the processor access mode 
from the PSL and writes the value into this field. 

IRP$I_PID* 

Process identification of the process that issued the I/O 
request. EXESQIO obtains the process identification from 
the process-control block and writes the value into this 
field. 

IRP$I_AST* 

Address of the AST routine specified by the user in the 

I/O request. If the process specifies an AST routine 
address in the QIO call, EXE$QIO writes the address in 
this field. 

During I/O postprocessing, the kernel-mode-AST routine 
queues a user mode AST to the requesting process if this 
field contains the address of an AST routine. 

IRP$I_ASTPRM 

Address of a parameter to be sent as an argument to the 
AST routine specified by the user in the I/O request. If the 
process specifies an AST routine and a parameter to that 
AST routine in the QIO call, EXE$QIO writes the parameter 
in this field. 

During I/O postprocessing, the kernel-mode-AST routine 

queues a user mode AST if the IRP$I_AST field contains 

an address, and passes the value in IRP$I—ASTPRM to 
the AST routine as an argument. 
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Table A-10 (Cont.) Contents of an l/O-Request Packet 


Field Name 

Contents 

IRP$I_WIND 

Address of a window-control block (WCB) that describes 
the file being accessed in an I/O request. EXE$QIO writes 
this field if the I/O request refers to a file-structured 
device. The ACP reads this field. 

When a process gains access to a file on a file-structured 
device or creates a logical link between a file and a 
process I/O channel, the device ACP creates a window- 
control block that describes the virtual-to-logical mapping 
of the file data on the disk. EXE$QIO stores the address 
of this WCB in the IRP$I_WIND field. 

IRP$I_UCB* 

Address of the unit-control block for the device assigned 
to the process I/O channel. EXESQIO copies this value 
from the channel-control block. 

IRP$W_FUNC 

l/O-function code that identifies the function to be 
performed for the I/O request. The I/O request call 
specifies an l/O-function code; EXESQIO and driver FDT 
routines map the code value to its most basic level 
(virtual -> logical -> physical) and copy the reduced 
value into this field. 

IRP$B_EFN* 

Based on this function code, EXE$QIO calls FDT action 
routines to preprocess an I/O request. Six bits of the 
function code describe the basic function. The remaining 
10 bits modify the function. 

Event flag number and group specified in the I/O request. 

If the I/O request call does not specify an event flag 
number, EXE$QIO uses event flag 0 by default. EXESQIO 
writes this field. The I/O postprocessing routine calls 
SCHSPOSTEF to set this event flag when the I/O operation 
is complete. 

IRP$B_PRI* 

Base priority of the process when the I/O request was 
issued. EXESQIO obtains a value for this field from the 
process-control block. EXESINSERTIRP reads this field 
to insert an l/O-request packet into a priority-ordered 
pending-l/O queue. 
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Table A-10 (Cont.) Contents of an l/O-Request Packet 


Field Name 

Contents 

IRP$I_IOSB 

Virtual address of the process's l/O-status block that 
receives the final status of the I/O request at I/O 
completion. EXE$QIO writes a value into this field if 
the I/O request call specifies an IOSB address. The I/O 
postprocessing kernel-mode-AST routine writes two 
longwords of I/O status into the IOSB block after the I/O 
operation is complete. 

When an FDT routine aborts an I/O request by calling 
EXE$ABORTIO, EXE$ABORTIO zeroes the IRP$L_IOSB 
field so that I/O postprocessing does not write status into 
the block. 

IRP$W_CHAN* 

Index number of the process I/O channel for the request. 
EXE$QIO writes this field. 

IRP$W_STS 

Status of the I/O request. EXE$QIO initializes this field 
to 0. EXE$QIO, FDT routines, and driver fork processes 
modify this field according to the current status of the I/O 
request. I/O postprocessing reads this field to determine 
what sort of postprocessing is necessary (for example, 
deallocate system buffers and adjust quota usage). 
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Table A-10 (Cont.) Contents of an l/O-Request Packet 


Field Name 


IRP$I_SVAPTE 


Contents 


Bits in the IRP$W_STS field describe the type of I/O 
function, as follows: 


IRP$V_BUFIO 

IRP$V_FUNC 

IRP$V_PAGIO 

IRP$V_COMPLX 

IRP$V_VIRTUAL 

IRP$V_CHAINED 

IRP$V_SWAPIO 

IRP$V_DIAGBUF 

IRP$V_PHYSIO 

IRP$V_TERMIO 

IRP$V_MBXIO 

IRP$V_EXTEND 

IRP$V_FILACP 

IRP$V_MVIRP 

IRP$V_KEY 


Buffered-I/O function 
Read function 
Paging-1/0 function 
Complex-buffered-l/O function 
Virtual-I/O function 
Chained-buffered-l/O function 
Swapping I/O function 
Diagnostic buffer is present 
Physical-I/O function 

Terminal I/O (for priority increment 
calculation) 

Mailbox-I/O function 

An extended IRP is linked to this IRP 

File ACP I/O 

Mount-verification-l/O function 

IRP$I_KEYDESC contains the 

address of a key used for encryption 


For a direct I/O operation, specifies the virtual address of 
the first page-table entry (PTE) of the l/O-transfer buffer. 
FDT routines that lock pages in memory for a direct I/O 
transfer write the PTE address in this field. 


For a buffered I/O operation, specifies the address of the 
buffer in system address space. FDT routines that allocate 
system buffers for a buffered I/O transfer write this field. 

IOC$INITIATE copies the field into the device unit-control 

block field UCB$I_SVAPTE before transferring control to 

a device driver start I/O routine. 

I/O postprocessing uses this field to deallocate the system 
buffer for a buffered I/O operation or to unlock pages 
locked for a direct I/O operation. 
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Table A-10 (Cont.) Contents of an I/O-Request Packet 


Field Name 

Contents 

IRP$W_BOFF 

Byte offset into first page of a direct I/O transfer. FDT 
routines calculate this offset and write the field. 

IRP$I_BCNT 

For buffered I/O operations, FDT routines must write the 
number of bytes to be charged to the process in this field 
because these bytes are being used for a system buffer. 

IOC$INITIATE copies the field into the device unit-control 
block field UCB$W_BOFF before calling a device driver 
start-l/O routine. 

I/O postprocessing uses IRP$W_BOFF in conjunction 
with IRP$W_BCNT and IRP$L_SVAPTE to unlock pages 
locked for direct I/O. For buffered I/O, I/O postprocessing 
adds the value of IRP$W_BOFF to the process byte count 
quota. 

Byte count of I/O transfer. FDT routines calculate the 
count value and write the field. IOC$INITIATE copies the 
low-order word of this field into the UCB field UCB$W_ 
BCNT before calling a device driver's start-l/O routine. 

For a buffered-l/O-read function, I/O postprocessing uses 

IRP$I_BCNT to determine how many bytes of data to 

write to the user's buffer. 

IRP$I_IOST1 

The field UCB$W_BCNT points to the low-order word of 
this field to provide compatibility with previous versions of 
VAX/VMS. 

First I/O status longword. IOC$REQCOM and 
EXE$FINISHIO(C) write the contents of RO into this field. 
The I/O postprocessing routine copies the contents of this 
field into the user's l/O-status block. 

EXESZEROPARM copies a 0 and EXE$ONEPARM copies 

PI into this field. This field is a good place to put 
a Queue-I/O-Request argument (PI through P6) or a 
computed value. 

This field is also called IRP$I_MEDIA 

IRP$I_IOST2 

Second I/O status longword. IOC$REQCOM and 
EXE$FINISHIO(C) write the contents of R1 into this field. 
The I/O postprocessing routine copies the contents of this 
field into the user's l/O-status block. 
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Table A-10 (Cont.) Contents of an l/O-Request Packet 


Field Name 

Contents 

IRP$I_ABCNT 

This field is also known as IRP$B_CARCON. 

IRP$B_CARCON contains carriage control instructions to 
the driver. EXE$READ and EXE$WRITE copy the contents 
of P4 of the user's I/O request into this field. 

Accumulated bytes transferred in a virtual I/O transfer. 
Read and written by IOC$IOPOST after a partial virtual 
transfer. 

IRP$l_OBCNT 

The symbol UCB$W_ABCNT points to the low-order word 
of this field to provide compatibility with previous versions 
of VAX/VMS. 

Original transfer byte count in a virtual I/O transfer. Read 
by IOC$IOPOST to determine whether a virtual transfer is 
complete, or whether another I/O request is necessary to 
transfer the remaining bytes. 

The symbol UCB$W_OBCNT points to the low-order word 
of this field to provide compatibility with previous versions 
of VAX/VMS. 

IRP$I_SEGVBN 

Virtual block number of the current segment of a virtual 

I/O transfer. Written by IOC$IOPOST after a partial virtual 
transfer. 

IRP$I_DIAGBUF* 

Address of a diagnostic buffer in system address space. 

If the I/O request call specifies this address, and if a 
diagnostic buffer length is specified in the driver-dispatch 
table, and if the process has diagnostic privilege, EXESQIO 
copies the buffer address into this field. 

EXE$QIO allocates a diagnostic buffer in system address 
space to be filled by IOCSDIAGBUFILL during I/O 
processing. During I/O postprocessing, the kernel-mode- 
AST routine copies diagnostic data from the system buffer 
into the process diagnostic buffer. 

IRP$I_SEQNUM* 

I/O transaction sequence number. If an error is logged 
for the request, this field contains the universal error log 
sequence number. 
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Table A-10 (Cont.) Contents of an l/O-Request Packet 


Field Name 

Contents 

IRP$I_EXTEND 

Address of the l/O-request-packet extension linked to 
this packet. FDT routines write an extension address to 
this field when a device requires more context than the 
I/O-request packet can accommodate. This field is read by 
IOC$POST. IRP$V_EXTEND in IRP$W_STS is set if this 
extension address is used. 

IRPSI—ARB* 

Address of the access rights block. This block is located 
in the process-control block and contains the process 
privilege mask and UIC, which are set up as follows: 


ARB$Q_PRIV Quadword containing process 

privilege mask 


SPARE$L Unused longword 

ARB$I_UIC Longword containing process UIC 

IRP$I_KEYDESC 

The address of an encryption key 


A.10 l/O-Request-Packet Extension (IRPE) 

I/O-request-packet extensions hold additional I/O-request 
information for devices that require more context than the 
standard I/O-request packet can accommodate. IRP extensions 
are also used when more than one buffer (region) must be 
locked into memory for a direct I/O operation, or when a 
transfer requires a buffer that is larger than 64K bytes. An IRPE 
provides space for two buffer regions, each with a 32-bit byte 
count. 

FDT routines allocate IRPEs by calling EXE$ALLOCIRP. Driver 
routines link the IRP extension to the I/O-request packet, store 
the extension's address in IRP$1—EXTEND and set the bit field 
IRP$V_EXTEND in IRP$W_STS to show that an extension 
exists for the packet. The FDT routine initializes the contents 
of the IRPE. Any fields within the extension not described in 
Table A-11 can store driver-dependent information. 
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If the IRP extension specifies additional buffer regions, the 
FDT routine must use those buffer locking routines that 
perform coroutine calls back to the driver if the locking 
procedure fails (EXE$READLOCKR, EXE$WRITELOCKR, 
and EXE$MODIFYLOCKR). If an error occurs during the 
locking procedure, the driver must unlock all previously locked 
regions and deallocate the I/O-request-packet extension before 
returning to the buffer locking routine. 

IOC$IOPOST automatically unlocks the pages in region 1 (if 
defined) and region 2 (if defined) for all the IRP extensions 
linked to the packet undergoing completion progessing. 
IOC$IOPOST also deallocates all the IRPEs. 

The fields of the I/O-request-packet extension are illustrated in 
Figure A-11 and described in Table A-ll. 

Figure A—11 l/O-Request-Packet Extension (IRPE) 
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Table A—11 Contents of the l/O-Request-Packet Extension 

Field Name 

Contents 

IRPE$W_SIZE 

Size of the 1/0-request-packet extension. 
EXE$ALLOCIRP writes the constant 
IRP$C_LENGTH to this field. 

IRPE$B_TYPE 

Type of control block. EXE$ALLOCIRP 
writes the constant DYN$C_IRP to this 
field. 

IRPE$W_STS 

IRP extension status field. Bits in the 
status field describe the following 
condition. 


IRPE$V_EXTEND Another IRPE is 

linked to this one 

IRPE$I_SVAPTE 1 

System virtual address of the page-table 
entry that maps the start of region 1. 

FDT routines write this field. If the region 
is not defined, this field is zero. 

IRPE$W_BOFF 1 

Byte offset of region 1. FDT routines 
write this field. 

IRPE$I_BCNT 1 

Size in bytes of region 1. FDT routines 
write this field. 

IRPE$I_SVAPTE2 

System virtual address of the page-table 
entry that maps the start of region 2. Set 
by FDT routines. This field contains a 
value of zero if region 2 is not defined. 

IRPE$W_B0FF2 

Byte offset of region 2. This field is set 
by FDT routines. 

IRPE$I_BCNT2 

Size in bytes of region 2. FDT routines 
write this field. 

IRPE$I_EXTEND 

The address of the next IRPE for this IRP, 
if any 



A.11 Object-Rights Block (ORB) 


The object-rights block is a data structure that describes the 
rights a process must have in order to access the object with 
which the ORB is associated. 

The ORB is usually allocated when the device is connected by 
means of SYSGEN's CONNECT command. SYSGEN also sets 
the address of the ORB in UCB$l_ORB at that time. 
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When initializing the ORB, device drivers must first zero the 
ORB, then use the DPT_STORE macro to initialize the fields in 
the ORB. The fields of the object-rights block that are illustrated 
in Figure A-12 and described in Table A-12. 


Figure A-12 Object-Rights Block (ORB) 
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Table A-12 Contents of Object-Rights Block 


Field 


Use 


ORB$l _OWNER 
ORB$l_ACI—MUTEX 

ORB$W_SIZE 
ORB$B_TYPE 


The UIC of the object's owner. 

Mutex for this object's ACL, used to control access to 
the ACL for reading and writing 

Size, in bytes, of the ORB (ORB$K_LENGTH) 

A code signifying that this is an ORB (DYN$C_ORB) 
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Table A—12 (Cont.) 

Contents of Object-Rights Block 

Field 

Use 


ORB$B_FLAGS 

Flags needed for interpreting portions of the ORB that 
can have alternate meanings. The following fields are 
defined within ORB$B_FLAGS. 


Field 

Use 


ORB$ V_PROT_ 16 

This flag must be set to 1 


ORB$V_ACI_QUEUE 

This flag should be set to 1; if 
it's 0, then ORB$l_ACLFL and 
ORB$l_ACLBL must contain 0 


ORB$V_NOACL 

This object cannot have an 

ACL 

ORB$W_PROT 

Standard SOGW protection 

ORB$l_ACLFL 

ACL queue forward link 


ORB$l_ACLBL 

ACL queue backward link 



A. 12 Unit-Control Block (UCB) 

The unit-control block is a variable-length block that describes 
a single device unit. Each device unit on the system has its own 
unit-control block. The block describes or provides pointers to 
the device type, controller, driver, device status, and current 
I/O activity. 

During autoconfiguration, the driver-loading procedure creates 
one unit-control block for each device unit in the system. A 
privileged system user can request the driver-loading procedure 
to create unit-control blocks for additional devices with the 
SYSGEN command CONNECT as described in Chapter 14. 

The procedure creates unit-control blocks of the length specified 
in the driver-prologue table of the device's driver. The driver 
uses UCB storage located beyond the standard UCB fields for 
device-specific data and temporary driver storage. 
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The driver-loading procedure initializes some static unit-control 
block fields when it creates the block. VAX/VMS and device 
drivers can read and modify all nonstatic fields of the unit- 
control block. 

The fields of the unit-control block that are present for 
all devices are illustrated in Figure A-13 and described in 

Table A-13. 

Table A-13 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$I_FQFL* 

Fork queue forward link. The link points to the next entry 
in the fork queue. EXE$IOFORK and VAX/VMS resource 
management routines write this field. The queue contains 
addresses of UCBs that contain driver fork process 
context of drivers waiting to continue I/O processing. 

UCB$I_FQBL* 

Fork queue backward link. The link points to the previous 
entry in the fork queue. EXE$IOFORK and VAX/VMS 
resource management routines write this field. 

UCB$W_SIZE* 

Size of the UCB. The driver-prologue table of every driver 
must specify a value for this field. The driver-loading 
procedure uses the value to allocate space for a UCB 
and stores the value in each UCB created. Extra space 
beyond the standard bytes in a UCB (UCB$K_LENGTFI) is 
for device-specific data and temporary storage. 

UCB$B_TYPE* 

Type of the control block. The driver-loading procedure 
writes the constant DYN$C_UCB into this field when the 
procedure creates the UCB. 

UCB$B_FIPL* 

Fork interrupt priority level (IPL) at which the driver of 
the device usually executes. The driver-prologue table 
of every driver must specify a value for this field. The 
driver-loading procedure writes the value in the UCB 
when the procedure creates the UCB. 

VAX/VMS creates a driver fork process that gains 
control in a driver start-l/O routine at this IPL. When 
the driver creates a fork process after an interrupt, 
VAX/VMS inserts the fork block into a fork queue based 
on this IPL. A VAX/VMS fork dispatcher executing 
at UCB$B_FIPL dequeues the fork block and restores 
control to the suspended driver fork process. 
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Figure A-13 Unit-Control Block (UCB) 
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Table A—13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$I_FPC 

All devices that are attached to one UNIBUS adapter and 
actively compete for shared UNIBUS adapter resources 
and/or a controller data channel must specify the same 
value for the fork IPL field. 

Fork process driver PC address. When a VAX/VMS 
routine saves driver fork context in order to suspend 
driver execution, the routine stores the address of the 
next driver instruction to be executed in this field. A 
VAX/VMS routine that reactivates a suspended driver 
transfers control to the saved PC address. 

UCB$I_FR3 

VAX/VMS routines that suspend driver 
processing include EXE$IOFORK, IOC$REQxCHANx 
IOC$REQMAPREG, IOCSREQDATAP, and IOC$WFIKPCH. 
Routines that reactivate suspended drivers include 
IOC$RELCHAN, IOC$RELMAPREG, IOC$RELDATAP, 
EXE$FORKDSPTH, and driver interrupt-servicing routines. 

When a driver interrupt-servicing routine determines that 
a device is expecting an interrupt, the routine restores 
control to the saved PC address in the device's UCB. 

Value of R3 at the time that a VAX/VMS routine 
suspends a driver fork process. The value of R3 is 
restored just before a suspended driver regains control. 

UCB$I_FR4 

Value of R4 at the time that an operating system routine 
suspends a driver fork process. The value of R4 is 
restored just before a suspended driver regains control. 

UCB$W_BUFQUO* 

UCB$W_SRCADDR* 

UCB$l_ORB* 

Buffered I/O quota if this UCB represents a mailbox. 

Local connection number for DECnet. 

The address of the object-rights block associated with 
this UCB. SYSGEN places the address in this field when 
you use SYSGEN's CONNECT command. 

UCB$l_LOCKID* 

UCB$I_CRB* 

The id of the lock on this device. 

Address of the primary channel-request block associated 
with the device. The driver-loading procedure writes 
this field after it creates the associated CRB. Driver 
fork processes read this field to gain access to device 
registers. VAX/VMS routines use UCB$I_CRB to 
locate interrupt-dispatching code and initialization-routine 
addresses. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$I_DDB* 

Address of the device-data block associated with 
the device. The driver-loading procedure writes this 
field when the procedure creates the associated UCB. 
VAX/VMS routines generally read the DDB field in order 
to locate device driver entry points, the address of a 
driver function-decision table, or the ACP associated with 
a given device. 

UCB$I_PID* 

Process identification code of the process that has 
allocated the device. Written by $ALLOC. 

UCB$I_LINK* 

Address of the next UCB in the chain of UCBs attached 
to a single controller and associated with a device¬ 
data block. The driver-loading procedure writes this 
field when the procedure adds the next UCB. Any 
VAX/VMS routines that examine the status of all devices 
on the system read this field. Such routines include 
EXE$TIMEOUT, IOC$SEARCHDEV, and power failure 
recovery routines. 

UCB$I_VCB* 

Address of the volume-control block (VCB) that describes 
the volume mounted on the device. This field is written 
by the device's ACP and read by EXESQIOACPPKT and 
ACPs. 

UCB$I_DEVCHAR 

First longword of device characteristics bits. The driver- 
prologue table of every driver should specify symbolic 
constant values (defined by the $DEVDEF macro) for this 
field. The driver-loading procedure writes the field when 
the procedure creates the UCB. The Queue-I/O-Request 
system service reads the field to determine whether a 
device is spooled, file-structured, shared, has a volume 
mounted, and so on. 

The system defines the following device characteristics: 
DEV$V_REC Record-oriented device 

DEV$V_CCL Carriage control device 

DEV$V_TRM Terminal device 

DEV$V_DIR Directory-structured device 
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Table A-13 (Cont.) 

Contents of Unit- 

-Control Block 

Field Name 

Contents 



DEV$V_SDI 

Single directory-structured device 


DEV$V_SQD 

Sequential block-oriented device 
(magnetic tape,for example) 


DEV$V_SPL 

Device is being spooled 


DEV$V_OPR 

Device is an operator device 


DEV$V_RCT 

Device contains RCT 


DEV$V_NET 

Network device 


DEV$V_FOD 

Files-oriented device (disk and 
magnetic tape, for example) 


DEV$V_DUA 

Device is dual ported 


DEV$V_SHR 

Shareable device (used by more 
than one program simultaneously 


DEV$V_GEN 

Generic device 


DEV$V_AVL 

Device is available for use 


DEV$V_MNT 

Device is mounted 


DEV$V_MBX 

Mailbox device 


DEV$V_DMT 

Device is marked for dismount 


DEV$V_ELG 

Error-logging is enabled on device 


DEV$V_ALL 

Device is allocated 


DEV$V_FOR 

Device is mounted foreign (not 
file-structured) 


DEV$V_SWL 

Device is software write-locked 
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Table A-13 (Cont.) 

Contents of Unit- 

-Control Block 

Field Name 

Contents 



DEV$V_IDV 

Device is capable of providing 
input 


DEV$V_ODV 

Device is capable of providing 
output 


DEV$V_RND 

Device allows random access 


DEV$V_RTM 

Real-time device 


DEV$V_RCK 

Read-checking is enabled on 
device 


DEV$V_WCK 

Write-checking is enabled on 
device 

UCB$B_DEVCHAR2 

Second longword of device characteristics. The driver- 
prologue table of every driver should specify symbolic 
constant values (defined by the $DEVDEF macro) for this 
field. The driver-loading procedure writes the field when 
the procedure creates the UCB. The Queue-I/O-Request 
system service reads the field to determine whether a 
device is spooled, file-structured, shared, has a volume 
mounted, and so on. 
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Table A-13 (Cont.) Contents of Unit-Control Block 


Field Name Contents 


The system defines the following device characteristics: 
DEV$V_CLU Device is available cluster-wide 


DEV$V_DET 

DEV$V_RTT 

Device is a detached terminal 

Device has a remote-terminal 

UCB extension 

DEV$V_CDP 

DEV$V_2P 

A dual-path device with 2 UCBs 

Two paths are known to this 
device 

DEV$V_MSCP 

This disk or tape is accessed 
using MSCP 

DEV$V_SSM 

DEV$V_SRV 

Reserved to DIGITAL 

This device is served by the 
MSCP server 

DEV$V_RED 

This device is a redirected 
terminal 

DEV$V_NNM 

The name of this device is 
prefixed by a node name and 
a $; if this bit is set, the string 
that consists of the device 
designation, the controller 
designation, and the largest 
possible unit number must total 
less than eight characters, so that 
the name of the device, including 
the node-name prifix, totals less 
than 16 characters. 


UCB$B_DEVCLASS Device class. The driver-prologue table of every 

driver should specify a symbolic constant (defined by 
the SDCDEF macro) for this field. The driver-loading 
procedure writes this field when the UCB is created. 

Drivers with set mode and device characteristics 
functions rewrite the value in this field with data supplied 
in an I/O request. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 


The VAX/VMS system defines the following device 
classes: 


DCS—DISK 

DC$_TAPE 

DC$_SCOM 


Disk device 
Tape device 

Synchronous communications 
device 


DC$_CARD 

DC$_TERM 

DC$_LP 

DC$_REALTIME 

DC$_MAILBOX 


Card reader device 
Terminal device 
Line printer device 
Real time device 
Mailbox device 


Note that the definition of a device as a real-time device 
is somewhat subjective; it implies no special treatment 
by VAX/VMS. 

UCB$B_DEVTYPE Device type. The driver-prologue table of every driver 

should specify a symbolic constant (defined by the 
SDCDEF macro) for this field. The driver-loading 
procedure writes the field when the procedure creates 
the UCB. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with data supplied 
in an I/O request. 

UCB$W_DEVBUFSIZ Default buffer size. The driver-prologue table can specify 

a value for this field if relevant. The driver-loading 
procedure writes the field when the procedure creates 
the UCB. 


Drivers with set mode and device characteristics 
functions rewrite the value in this field with data supplied 
in an I/O request. This field is used by RMS for record 
I/O on non-file-oriented devices. 

UCB$I_DEVDEPEND Device-dependent data. Contains device- descriptive 

data that only the device driver can interpret. The 
driver-prologue table can specify a value for this field. 
The driver-loading procedure writes this field when the 
procedure creates the UCB. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$I_DEVDEPND2 

Drivers with set mode and device characteristics 
functions rewrite the value in this field with data supplied 
in an I/O request. 

Second longword for device-dependent status. This field 
is an extension of UCB$I_DEVDEPEND. 

UCB$l_IOQFL* 

I/O queue listhead forward link. The queue contains the 
addresses of l/O-request packets waiting for processing 
on a device. EXE$INSERTIRP inserts l/O-request packets 
into the pending-l/O queue when a device is busy. 
IOC$REQCOM dequeues l/O-request packets when the 
device is idle. 

UCB$l_IOQBL* 

The queue is a priority queue that has the highest priority 
packets at the front of the queue. Priority is determined 
by the base priority of the requesting process. Packets 
with the same priority are processed first-in/first-out. 

I/O queue listhead backward link. EXE$INSERTIRP and 
IOC$REQCOM modify the pending-l/O queue. 

UCB$W_UNIT* 

Number of the physical device unit. Stored as a binary 
value. The driver-loading procedure writes a value into 
this field when the UCB is created. Drivers for multiunit 
controllers read this field during unit initialization to 
identify a unit to the controller. 

UCB$W_CHARGE* 

Mailbox byte count quota charge, if the device is a 
mailbox. 

UCB$I_IRP 

Address of the l/O-request packet currently being 
processed on the device unit by a driver fork process. 
IOC$INITIATE writes the address of an l/O-request 
packet into this field before the routine creates a driver 
fork process to handle an I/O request. From this field a 
driver fork process obtains the address of the l/O-request 
packet being processed. 

The value contained in this field is valid if the UCB$V_ 
BSY bit in UCB$S_STS is set. 

UCB$W_REFC* 

Reference count of processes that currently have process 
I/O channels assigned to the device. Incremented by the 
$ASSIGN and SALLOC system services. Decremented by 
the SDASSGN and $DALLOC system services. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 


UCB$B_DIPL Device interrupt priority level at which the device requests 

hardware interrupts. The driver-prologue table of every 
driver must specify a value for this field. The driver¬ 
loading procedure writes the field when the procedure 
creates the UCB. 


UCB$B_AMOD* 

UCB$I_AMB* 

UCB$I_STS 


Some device drivers raise IPL to this value before reading 
or writing device registers. 

If the device unit is allocated, the access mode at which 
the allocation occurred. Written by the SALLOC and 
$DALLOC system services. 

Associated mailbox UCB pointer. This field is used for 
spooled devices and mailboxes. 

Device unit status, formerly UCB$W_STS. Written by 
drivers, IOCSREQCOM, IOCSCANCELIO, IOC$INITIATE, 
IOC$WFIKPCH, IOC$WFIRLCH, EXE$INSIOQ, and 
EXE$TIMEOUT. This field is read by drivers, the Queue- 
l/O-Request system service routines, IOCSREQCOM, 
IOCSINITIATE, and EXE$TIMEOUT. 

This longword includes the following bits: 

UCB$V_TIM Timeout enabled 

UCB$V_INT Interrupts expected 


UCB$V_ERLOGIP 

UCB$V_CANCEL 

UCB$V__ONLINE 

UCB$V_POWER 


Error log in progress 
Cancel I/O on unit 
Device is on line 

Power has failed while unit 
was busy 


UCB$V_TIMOUT 

UCB$V_INTTYPE 

UCB$V_BSY 

UCB$V_MOUNTING 


Unit is timed out 
Receiver interrupt 
Unit is busy 

Device is being mounted 


UCB$V_DEADMO Deallocate device at dismount 
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Table A—13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 



UCB$V_VALID 

Software believes volume is 
valid 


UCB$V_UNLOAD 

Unload volume at dismount 


UCB$V_TEMPLATE 

Template unit-control block 
from which other UCBs for 
this device are made. The 
SASSIGN system service 
checks this bit in the 
requested UCB and, if the 
bit is set, creates a UCB from 
the template. The new UCB is 
assigned instead. 


UCB$V_MNTVERIP 

Mount verification in progress 


UCB$V_WRONGVOL 

Volume name does not match 
name in the volume-control 
block 


UCB$V_DELETEUCB 

Delete this UCB when the 
value in UCB$W_REFC 
becomes zero 


UCB$V_LCI_VALID 

The volume on this device is 
valid on the local node 


UCB$V_SUPMVMSG 

Suppress mount-verification 
messages if they indicate 
success 


UCB$V_MNTVERPND 

Mount verification is pending 
on the device and the device 
is busy 

UCB$W_DEVSTS 

Device-dependent status, 
drivers. 

Read and written by device 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$W_QLEN 

The system defines the following status bits: 

UCB$V_JOB The job-controller has been 

notified 

UCBTV_TEMPI_BSY The template UCB is busy 

UCB$V_PRMMBX Device is a permanent mailbox 

UCB$V_DELMBX Mailbox is marked for deletion 

UCB$V_SHMMBS Shared-memory mailbox 

The length of the queue of I/O requests to which UCB$I_ 
IOQFL points 

UCB$I_DUETIM* 

Due time for I/O completion. Stored as the low-order 
32-bit absolute time (time in seconds since the operating 
system was booted) at which the device will timeout. 
IOC$WFIKPCH and IOC$WFIRLCH write this value when 
they suspend a driver to wait for an interrupt or timeout. 

EXE$TIMEOUT examines this field in each UCB in the I/O 
database once per second. If the timeout has occurred 
and timeouts are enabled for the device, EXE$TIMEOUT 
calls the device driver timeout handler. 

UCB$l_OPCNT* 

Count of operations completed on the device unit since 
VAX/VMS was booted. IOC$REQCOM writes this field 
every time the routine inserts an l/O-request packet in 
the I/O postprocessing queue. 

UCB$I_SVPN* 

Index to a virtual address of a system-page-table entry 
permanently allocated to the device by the driver-loading 
procedure. The system virtual address of the page 
described by this index can be calculated by the formula 

(index * 200) + 80000000 (hex) 


If a driver-prologue table specifies DPT$M_SVP in the 
flags argument to the DPTAB macro, the driver-loading 
procedure allocates a page of nonpaged system memory 
to the device. The procedure writes the system-page- 
table entry's index into UCB$I_SVPN when the procedure 
creates the UCB. 

This field is used for ECC error correction by disk drivers. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$I_SVAPTE 

For a direct I/O operation, the virtual address of the 
system-page-table entry (PTE) for the first page that is to 
be used in an I/O transfer. For a buffered I/O operation, 
the address of the system buffer used in the transfer. 
This field is used only in transfer operations. 

IOC$INITIATE writes this field from IRP$I_SVAPTE 
before calling a driver start-l/O routine. Drivers read this 
value to compute the starting address of a transfer. 

UCB$W_BOFF 

For direct I/O operations, byte offset in first page of 
the transfer buffer. For buffered I/O operations, the 
number of bytes charged to a process for a transfer. 
IOC$INITIATE copies this field from the l/O-request 
packet. 

Drivers read the field in calculating the starting address 
of a DMA transfer. If only part of a DMA transfer 
succeeds, the driver adjusts the value in this field to be 
the byte offset in the first page of the data that was not 
transferred. 

UCB$W_BCNT 

Count of bytes in I/O transfer. IOC$INITIATE copies 
this field from the l/O-request packet. Drivers read this 
field to determine how many bytes to transfer in an I/O 
operation. 

UCB$B_ERTCNT 

Error retry count of current I/O transfer. The driver sets 
this field to the maximum retry count each time it begins 
I/O processing. Before each retry, the driver decreases 
the value in this field. If error-logging is occurring, 
IOC$REQCOM copies the value into the error message 
buffer. 

UCB$B_ERTMAX 

Maximum error retry count allowed for a single I/O 
transfer. The driver-prologue table of some drivers 
specifies a value for this field. The driver-loading 
procedure writes the field when the procedure creates 
the UCB. If error-logging is occurring, IOC$REQCOM 
copies the value into the error message buffer. 
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Table A-13 (Cont.) 

Contents of Unit-Control Block 

Field Name 

Contents 

UCB$W_ERRCNT 

Number of errors that have occurred on the device 
since the system was bootstrapped. The driver-loading 
procedure initializes the field to 0 when the procedure 
creates the UCB. ERL$DEVICERR and ERLSDEVICTMO 
increment the value in the field and copy the value into an 
error message buffer. The DCL command SHOW DEVICE 
displays in its error count column the value contained in 
this field. 

UCB$I_PDT» 

Address of the port-descriptor table. This field is 
reserved for VAX/VMS port drivers. 

UCB$I_DDT‘ 

Address of the driver-dispatch table for this unit. The 
driver load procedure writes the contents of DDB$I_DDT 
for the device controller to this field when it creates the 
UCB. 


Unit-control blocks are variable length depending on the type 
of device and whether the driver performs error-logging for the 
device. The error log UCB extension, if present, appears at the 
end of the standard UCB. 

The fields in the UCB error log extension are illustrated in 
Figure A-14 and described in Table A-14. 


Figure A-14 UCB Error Log Extension 


UCB$B_CEX 

UCB$B_FEX 

UCB$B_SPR 

UCB$B _ SLAVE* 

UCB$I_EMB* 

UCB$W_FUNC 

unused 

UCB$I_DPC 


ZK-1 790-84 
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Table A-14 UCB Error Log Extension 


Field Name Contents 


UCB$B_SLAVE* 

UCB$B_SPR 

UCB$B_FEX 

UCB$B_CEX 

UCB$I_EMB* 


UCB$W_FUNC 

UCB$I_DPC 


Unit number of slave controller. 

Spare byte. This field is reserved for driver 
use. MASSBUS adapter drivers use this 
field to store a fixed offset to the MASSBUS 
adapter registers for the unit. 

Device-specific field. This field is reserved 
for driver use. 

Device-specific field. This field is reserved 
for driver use. 

Address of the error message buffer. If error 
logging is enabled and a device/controller 
error or timeout occurs, the driver calls 
ERL$DEVICERR or ERL$DEVICTMO to 
allocate an error message buffer and 
copy the buffer address into this field. 
IOCSREQCOM writes final device status, 
error counters, and I/O request status into 
the buffer specified by this field. 

l/O-function modifiers. This field is read and 
written by drivers that log errors. 

Device-specific field. This field is reserved 
for driver use. 


Another extension of the unit-control block is the disk-extension 
block. This UCB extension is present for all disk devices. It 
follows the error log extension. A driver that supports a disk 
must allow space in the UCB for both the error log and disk 
extensions. 

Disk drivers use three bits in UCB$W_DEVSTS as follows: 

UCB$V_ECC ECC correction made 

UCB$V_DIAGBUF Diagnostic buffer specifed 

UCB$V_NOCNVRT No logical block number to media address 

conversion 

The fields are illustrated in Figure A-15 and described in 
Table A-15. 
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Figure A-15 UCB Disk Extension 
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UCB$L_ 

_DCCB 


ZK-1791 -84 


Table A-15 UCB Disk Extension 


Field Name Contents 


UCB$W_DIRSEQ 


UCB$W_ONLCNT 

UCB$l_MAXBLOCK 


UCB$I_DCCB 


Directory sequence number. If the high- 
order bit of this word, UCB$V_AST_ 
ARMED, is set, it indicates that the 
requesting process is blocking ASTs. 

The number of times this device has been 
placed on line since the system booted 

Maximum number of logical blocks on a 
random-access device. This field is written 
by a disk driver during unit initialization and 
power recovery. 

Pointer to the cache-control block 


Another extension to the UCB is a local-disk extension, used by 
disks that are local to a processor as opposed to disks that are 
in a cluster with the processor. This UCB extension, if present, 
appears directly after the UCB's disk extension. 

The fields in the UCB local-disk extension are illustrated in 
Figure A-16 and described in Table A-16. 
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Figure A-16 UCB Error Log Extension 
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Table A-16 UCB Local-Disk Extension 


Field Name Contents 


UCB$I_MEDIA 

UCB$I_BCR 


UCB$W_EC1 


Media address. 

The byte-count register. Some disk 
drivers use this field as an internal 
count of the number of bytes left to 
be transferred in an I/O request. The 
symbol UCB$W_BCR points to the 
low-order work of this field. 

ECC position register. This field records 
the starting bit number of an error 
burst. Disk driver register dump routines 
copy the contents of this field into an 
error-logging or diagnostic buffer. 

The VAX/VMS correction routine 
IOCSAPPLYECC reads the contents of 
this field to locate the beginning of an 
error burst in a disk block. 
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Table A-16 (Cont.) UCB Local-Disk Extension 


Field Name Contents 


UCB$W_EC2 


UCB$W_OFFSET 

UCB$B_OFFNDX 


UCB$B_OFFRTC 

UCB$I_DX_BUF 

UCB$I_DX_BFPNT 

UCB$I_DX_RXDB 

UCB$W_BCR 

UCB$B_DX_SCTCNT 


ECC position register. Records the 
exclusive OR correction pattern. Disk 
driver register dump routines copy the 
contents of this field into an error¬ 
logging or diagnostic buffer. 

The VAX/VMS ECC correction routine 
IOC$APPLYECC reads the contents of 
this field to correct disk data. 

Current offset register contents. 

Current offset table index. When a disk 
driver transfer ends in an error, the disk 
driver can retry the error a number of 
times with different offsets of the disk 
head from the centerline. This field is 
an index into a driver table of offset 
positions. 

Current offset retry count. This field 
records the number of times to try a 
particular offset setting in a disk transfer 
retry. 

The address of the sector buffer; used 
by floppy-disk drivers. 

Pointer to the current sector; used by 
floppy-disk drivers. 

The address of the saved receiver-data 
buffer; used by floppy-disk drivers. 

Current floppy byte count; used by 
floppy-disk drivers. 

Current sector byte count; used by 
floppy-disk drivers. 
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VAX/VMS Macros Invoked by 
Drivers 


This chapter describes the VAX/VMS macros that drivers 
can use. Optional parameters are enclosed in brackets. If a 
parameter has a default value, that value is shown, separated 
from the parameter by an equal sign (=). 
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CASE 


CASE 

This macro generates a CASE instruction and its associated 
table. 

CASE SRC, DISPLIST, [TYPE=W], 
[LIMIT=0], - 
[NMODE=S#] 

SRC 

The source of the index value to be used with the CASE 
instruction 

DISPLIST 

The list of destinations to which control is to be dispatched, 
depending on the value of the index 

TYPE 

The datatype of SRC (B, W, or L) 

LIMIT 

The lower limit of the value of SRC 

NMODE 

The addressing mode used to reference the case-table entries; 
the default, short-literal mode, is good for up to 63 entries 
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DDTAB 


DDTAB 

This macro generates a driver-dispatch table labeled 
devnam$DDT. 

DDTAB DEVNAM, 

[START=IOC$RETURN], - 
[UNSOLICIT IOC$RETURN],- 
FUNCTAB, 

[CAIMCEL=IOC$RETURIM], - 

[REGDUMP !OC$RETURN], - 
[DIAGBUF O], [ERLGBFO], - 
[UNITINIT=IOC$RETURN], - 
[ALTSTART=IOC$RETURI\l],- 
[MNTVER=IOC$MIMTVER], - 
[CLONEDUCBIOCSRETURN] 

DEVNAM 

The generic name of the device 

[START=IOC$RETURN] 

The address of the start-I/O routine 

[UNSOLIC=IOC$RETURN] 

The address of the unsolicited-interrupt-servicing routine 

FUNCTB 

The address of the function-decision table 

[CANCEUIOCSRETURN] 

The address of the cancel-I/O routine 

[R EG DM P=IOC$ RETURN] 

The address of the register-dumping routine 

[DIAGBF=0] 

The length, in bytes, of the diagnostic buffer 
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[ERLGBF=0] 

The length, in bytes, of the error-logging buffer 

[UNITINIT=IOC$RETURN] 

The address of the unit-initialization routine 

[ALTSTART=IOC$RETURN] 

The address of the alternate start-I/O routine 

[MNTVER=IOC$MNTVER] 

The address of the mount-verification routine; the default is 
suitable for all single-stream disk drives. 

[CLONEDUCB=IOC$RETURN] 

The address of the routine called when a UCB is cloned by the 
$ASSIGN system service 
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DPTAB 


DPTAB 

This macro generates a driver-prologue table in a program 
section called $$$105__PROLOGUE. 

DPTAB END, ADAPTER, [FLAGS=0], 
UCBSIZE, - 

[UNLOAD], [MAXUNITS=8], 
[DEFUNITS=1 ], - 
[DELIVER], [VECTOR], NAME 


END 

The address of the end of the driver 


ADAPTER 

The type of adapter (UBA, MBA, DR, or NULL) 


[FLAGS=0] 

The flags used in loading the driver 


DPT$M_SVP 


DPT$M_ 

NOUNLOAD 


Indicates that the device requires a permanently 
allocated system page. This flag causes the 
driver-loading procedure to allocate a system- 
page-table entry for the device permanently. 

The system's driver-loading procedure writes 
the virtual address of the system-page-table 
entry into the system-page field of the UCB 

(UCB$I_SVPN) during creation of the UCB. 

Disk drivers use this page table entry during 
ECC error correction. 

Indicates that the driver cannot be reloaded. A 
driver with this bit set can be unloaded only by 
bootstraping the system 


UCBSIZE 

The size, in bytes, of the unit-control block required by each 
device that this driver will drive; this field allows drivers to use 
extensions to the UCB for storage of device-dependent data that 
describes an I/O operation. 


The amount that the UCB is extended varies for each type of 
driver. Driver routines and VAX/VMS ECC routines interpret 
fields in the extended part of the UCB. 
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DPTAB 


[UNLOAD] 

The address of the routine in the driver that SYSGEN is to call 
before unloading the driver and loading a new version of the 
driver. SYSGEN calls this routine when you use the RELOAD 
command. 

[MAXUNITS=8] 

The maximum number of device units that can be connected to 
the controller. This field affects the size of the IDB created by 
SYSGEN's CONNECT command. 

If this field is omitted, the default is 8 units. You can override 
the contents of this field by using the /MAXUNITS qualifier 
with the CONNECT command. 

[DEFUNITS=1 ] 

The maximum number of UCBs to be created by SYSGEN's 
AUTOCONFIGURE command (one for each device unit to 
be configured). The unit numbers assigned are zero through 
defunits-minus-one. 

If the DELIVER argument is present, it names a routine that the 
AUTOCONFIGURE command calls to determine whether to 
create each unit's data structures automatically. 

[DELIVER] 

The address of the routine in the driver that determines 
whether a unit should be configured automatically, the unit- 
delivery routine. 

If this argument is omitted, the AUTOCONFIGURE command 
creates the number of units specified by the DEFUNITS. 

[VECTOR] 

Reserved to DIGITAL; the address of a driver-specific transfer 
vector 

NAME 

The name of the device driver 


B—6 



VAX/VMS Macros Invoked by Drivers 

$DEF 



$DEF 


Drivers use this macro to define a data-structure field. This 
macro can only be used within the scope of a $DEFINI macro. 


$DEF SYM, [ALLOC], [SIZ] 


SYM 

The name of the symbol by which the field is to be accessed 

[ALLOC] 

Block-storage-allocation directives, one of the following: .BLKB, 
.BLKW, .BLKL, .BLKQ, or .BLKO. 

You can define a second symbolic name for the same field by 
using the $DEF macro a second time immediately following 
the first definition, leaving this parameter blank in the second 
invocation. 



[SIZ] 

Number of block-storage units to allocate 
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$DEFEND 

This macro ends the scope of the $DEFINI macro, thereby 
ending the definition of fields within the data structure. 

$DEFEND STRUC 

STRUC 

The name of the structure that is being defined 
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$DEFINI 

This macro initiates the definition of a data structure. The $DEF 
macro is used to define fields within this structure, and the 
$DEFEND macro ends the definition of this structure. 

$DEFINI STRUC, [GBL LOCAL], 
[DOT=0] 

STRUC 

The name of the data structure to be defined. 

[GBULOCAL] 

Specifies whether the symbols defined for this data structure 
are to be local or global symbols. The default is to make them 
local. 

To make the symbols' definitions global, you must use the 
GLOBAL argument with the GBL keyword. 

[DOT=0] 

The offset from the beginning of the data structure of the first 
field to be defined. The default is to make to offset zero. 
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DPT—STORE 

This macro, used within a driver, instructs the system's driver¬ 
loading procedure to store values in a table or data structure. 

DPT—STORE TYPE, OFFSET, OPER, 
EXP, POS, SIZE 

TYPE 

The type of control block into which the data is to be stored 
(DDB, UCB, ORB, CRB, or IDB), or a table marker (INIT, 
REINIT, or END). If this argument is a table marker, no other 
argument is allowed and the table affected is the DPT. 

OFFSET 

The offset from the beginning of the data structure at which the 
data is to be stored. This cannot be more than 255 bytes. 

OPER 

The type of storage operation, one of the following: 


Keyword 

Meaning 

B 

Byte 

W 

Word 

L 

Longword 

D 

Address relative to the beginning of the driver 

V 

Bit field 


If an at-sign character (@) precedes the OPER argument, then 
the EXP argument describes the address of the data with which 
to initialize the field. 


EXP 

The value with which to initialize the field; if OPER is preceded 
by an at-sign character (@), then the address at which to find 
the value with which to initialize the field 

[POS] 

The position of the bit affected; used only if OPER=V 

[SIZE] 

The size of the bit-field affected; used only if OPER=V 
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DSBINT 


DSBINT 

This macro disables interrupts occurring at or below the 
specified IPL and saves the current IPL in the specified 
longword. 

DSBINT [IPL=31 ], [DST=-(SP)] 

[IPU31] 

The IPL at which to block interrupts. If no IPL is specified, the 
default is IPL 31, which blocks all interrupts. 

[DST=-(SP)] 

The location in which to save the current IPL. If no destination 
is specified, the current IPL is pushed on the stack. 
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ENBINT 


ENBINT 

This macro enables interrupts at a specified IPL or at the IPL 
stored on the stack. 

ENBINT [SRC=(SP)+] 

[SRC={SP)+] 

The address of the IPL at which to enable interrupts. If no SRC 
is specified, the IPL is popped from the top of the current stack. 
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$EQULST 


SEQULST 

This macro defines a list of symbols and assigns values to the 
symbols. 

$EQULST PREFIX, [GBL LOCAL], 
INIT, [INCR=1], - 
LIST 


PREFIX 

The prefix to be used in forming the names of the symbols, and 
VALUE is the value assigned to the symbol. 

[GBULOCAL] 

The scope of the definition of the symbol, either LOCAL, the 
default, or GLOBAL. 

INIT 

The value to be assigned to the first symbol in the list. 

[INCFU1] 

The increment by which to increase the value of each 
succeeding symbol in the list. The default is 1. 

LIST 

The list of symbols to be defined. Each element in the list can 
have one of the following forms. 

SYMBOL, where symbol is the string appended to the prefix, 
forming the name of the symbol; the value of the symbol is 
assigned based on the values of INIT and INCR. 

<SYMBOL,VALUE>, where symbol is the string that is 
appended to the prefix, forming the name of the symbol. 
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FORK 


FORK 

Drivers use this macro to create, by calling EXE$FORK, a 
fork process, in which context the code following the macro 
invocation executes. 

FORK 

When this macro is invoked, it is necessary that the following 
registers contain the values listed below. 


Register Contents 

R3 The contents of the fork's R3 

R4 The contents of the fork's R4 

R5 The address of a fork block 

(SP) The address of the caller's caller 
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FUNCTAB 

This macro generates an entry for a function-decision table. 

FUNCTAB [ACTION], codes 

[ACTION] 

The routine to call when the function code specified in the I/O 
request matches the code argument to this macro; if this is to be 
the first or second entry in the table, this argument must not be 
supplied. 

codes 

The code or codes for which the routine specified in the first 
argument to this macro is to be called; the codes are specified 
as the I/O-function codes of the form, IO$_xxx, but without 
the IO$ prefix. 


B-15 




VAX/VMS Macros Invoked by Drivers 

IFNORD 


IFNORD 

This macro uses the PROBER instruction to check the 
accessibility of the specified range of memory by checking 
the accessibility of the first and last bytes in that range. 

If both can be read in the specified access mode, this macro 
dispatches control to the destination specified in the third 
argument to this macro. Otherwise this macro passes control to 
the next in-line instruction. 

IFNORD SIZ, ADR, DEST, [MODE=#0] 

siz 

The offset of the last byte to check from the first byte to check, 
a number less than or equal to 512. 

ADR 

The address of the first byte to check. 

DEST 

The address to which this macro passes control if both bytes 
can be read. 

[MODE=#0] 

The mode in which access is to be checked; zero, the default, 
causes the check to be performed in the mode contained in the 
previous-mode field of the current PSL. 
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IFNOWRT 

This macro uses the PROBEW instruction to check the 
accessibility of the specified range of memory by checking 
the accessibility of the first and last bytes in that range. 

If the specified bytes can be written in the specified access 
mode, this macro passes control to the address specified in the 
third argument to this macro. Otherwise it passes control to the 
next in-line instruction. 

IFNOWRT SIZ, ADR, DEST, 
[MODE=#0] 

siz 

The offset from the first byte to check to the second byte to 
check; this number must be less than or equal to 512. 

ADR 

The address of the first byte to check. 

DEST 

The address to which this macro passes control if both bytes 
can be written in the specified access mode. 

[MODE=#0] 

The mode in which to check access to the bytes; zero, the 
default, causes the check to be made in the mode contained in 
the previous-mode field of the current PSL. 
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IFRD 


IFRD 

This macro checks the accessibility of the specified range of 
memory by checking the accessibility of the first and last bytes 
in that range. 

It passes control to the specified destination if both bytes can be 
read in the specified access mode. Otherwise control is passed 
to the next in-line instruction. 

IFRD SIZ, ADR, DEST, [MODE #0] 

siz 

The offset from the first byte to check of the second byte to 
check; only the first and last bytes in the range are checked. 

ADR 

The address of the first byte to check. 

DEST 

The address to which this macro passes control if either byte 
cannot be read in the specified access mode. 

[MODE=#0] 

The mode in which to check read access; zero, the default, 
causes the check to be made in the mode contained in the 
previous-mode field of the current PSL. 
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IFWRT 


IFWRT 

This macro checks the accessibility of the specified range of 
memory by checking the accessibility of the first and last bytes 
in that range. 

It causes control to branch if the specified destination is 
writeable. 

IFWRT SIZ, ADR, DEST, [MODE=#0] 

siz 

The offset from the first byte to check of the second byte to 
check; only the first and last bytes in the specified range are 
checked. 

ADR 

The address of the first byte to check 

DEST 

The address to which this macro passes control if either byte 
cannot be written in the specified access mode 

MODE=#0 

The mode in which to check write access; the default is USER 
mode 
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IOFORK 


IOFORK 

This macro calls EXE$IOFORK to create a fork process for a 
device driver. This macro clears the bit UCB$V_TIM in the 
field UCB$W_STS, whereas the FORK macro does not. 

IOFORK 

When this macro is invoked, the following registers must 
contain the values listed below. 


Register Contents 

R3 The contents of the fork's R3 

R4 The contents of the fork's R4 

R5 The address of the UCB that will be used as a fork 

block for the fork process to be created 

(SP) The address of the caller's caller 
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LOADMBA 


LOADMBA 

This macro calls IOC$LOADMBAMAP in order to load 
MASSBUS mapping registers. The driver must own the 
MASSBUS adapter, and thus the mapping registers, before 
it can invoke this macro. 

LOADMBA 

When this macro is invoked, the following registers must 
contain the values listed below. Note that this macro destroys 
the contents of registers RO through R2. 


Register Contents 

R4 The address of the MBA's CSR 

R5 The address of the UCB 
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LOADUBA 


LOADUBA 

This macro calls IOC$LOADUBAMAP in order to load the 
UNIBUS adapter's registers. The registers must already be 
allocated before this macro can be invoked. 

LOADUBA 

When this macro is invoked, register R5 must contain the 
address of the UCB. 

Note that this macro destroys the contents of registers RO 
through R2. 
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PURDPR 


PURDPR 

This macro calls IOC$PURDATAP in order to purge a data 
path. 

PURDPR 

When this macro is invoked, register R5 must contain the 
address of the UCB. 

When this macro returns control to its caller, the registers 
contain the values listed below. 


Register Contents 

RO The status of the purge (success or failure) 

R1 The contents of the data-path register, provided for 

the use of the driver's register-dumping routine 

R2 The address of the first mapping register, provided 

for the use of the driver's register-dumping routine 


Note that this macro destroys the contents of R3. 
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RELCHAN 


RELCHAN 

This macro calls IOC$RELCHAN in order to release all data 
channels (controllers) allocated to the device. 

RELCHAN 

When this macro is invoked, R5 must contain the address of the 
UCB. 

This macro destroys the contents of registers RO through R2. 
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RELDPR 


RELDPR 

This macro calls IOC$RELDATAP in order to release a UNIBUS 
data path register allocated to the driver. 

RELDPR 

When this macro is invoked, R5 must contain the address of the 
UCB. This macro destroys the contents of registers RO through 
R2. 
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RELMPR 


RELMPR 

This macro calls IOC$RELMAPREG in order to release a set of 
UNIBUS mapping registers allocated by the driver. 

RELMPR 

When this macro is invoked, R5 must contain the address of the 
UCB. This macro destroys the contents of RO through R2. 
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RELSCHAN 


RELSCHAN 

This macro calls IOC$RELSCHAN in order to release all 
secondary data channels allocated by the driver. 

RELSCHAN 


When this macro is invoked, R5 must contain the address of the 
UCB. This macro destroys the contents of RO through R2. 
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REQCOM 


REQCOM 

This macro calls IOC$REQCOM in order to complete the 
processing of an I/O request after the driver has finished its 
portion of the processing. 

REQCOM 


When this macro is invoked, R5 must contain the address of the 
UCB. This macro destroys the contents of RO through R2. 
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REQDPR 


REQDPR 

This macro calls IOC$REQDATAP in order to request a data 
path in a UNIBUS adapter. 

REQDPR 

When this macro is invoked, the following registers must 
contain the values listed. 


Register Contents 

R5 The address of the UCB 

(SP) The address of the caller's caller 


This macro destroys the contents of RO through R2. 
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REQMPR 


REQMPR 

This macro calls IOC$REQMAPREG in order to obtain UNIBUS 
mapping registers. 

REQMPR 

When this macro is invoked, the following registers must 
contain the values listed. 


Register Contents 

R5 The address of the UCB 

(SP) The address of the caller's caller 


This macro destroys the contents of RO through R2. 
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REQPCHAN 


REQPCHAN 

This macro calls IOC$REQPCHANH or IOCSREQPCHANL, 
depending on the priority specified, to obtain a UNIBUS or 
MASSBUS data channel. 

REQPCHAN [PRI] 

[PRl] 

The priority of the request. If the priority is HIGH, this 
macro calls IOCSREQPCHANH; otherwise this macro calls 
IOCSREQPCHANL 

When this macro is invoked, the following registers must 
contain the values listed. 


Register Contents 

R5 The address of the UCB 

(SP) The address of the caller's caller 


This macro destroys the contents of RO through R2. 
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REQSCHAN 


REQSCHAN 

This macro calls IOC$REQSCHANH or IOC$REQSCHANL, 
depending on the priority specified, to obtain a secondary 
MASSBUS data channel. 

REQSCHAN 

[PRI] 

The priority of the request. If the priority is HIGH, this 
macro calls IOC$REQSCHANH; otherwise this macro calls 
IOC$REQSCHANL 

When this macro is invoked, the following registers must 
contain the values listed. 


Register Contents 

R5 The address of the UCB 

(SP) The address of the caller's caller 


This macro destroys the contents of RO through R2. 
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SAVIPL 

This macro saves the current IPL, as recorded in the processor 
register PR$_JPL, in the location specified or on the stack. 

SAVIPL [DEST=-(SP>] 

[DEST=-(SP)] 

The address of the longword in which to save the current IPL; 
the default is to push the IPL on the stack 
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SETIPL 

This macro sets the current IPL by moving the specified value 
into the processor register PR$_JPL. 

SETIPL [IPL=31 ] 

[IPU31] 

The level at which to set the current IPL; the default is IPL 31 
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SOFTINT 


SOFTINT 

This macro moves the specified IPL into processer register 
PR$_SIRR, requesting a software interrupt at that IPL. 

SOFTINT IPL 

IPL 

The IPL at which the interrupt is to occur 
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TIMEWAIT 

This macro checks for a specific state by testing bits for a 
specified length of time. Use of the TIMEDWAIT macro instead 
of this macro is recommended. 

If the state comes into existence during the specified interval, 
this macro places a success code in RO and returns control to its 
caller. 

If the state does not occur during the specified period, this 
macro places a failure code in RO and returns control to its 
caller. 

TIMEWAIT TIME, BITVAL, SOURCE, 
CONTEXT, - 
[SENSE.TRUE.] 


TIME 

The number of 10-microsecond intervals to wait 

BITVAL 

The mask that determines which bits to test 

SOURCE 

The address of the bits to test 

CONTEXT 

Context in which the bits are to be tested (B, W, or L) 

[SENSE=.TRUE.] 

If .TRUE., test for one or more of the specified bits set- 
otherwise test for all bits cleared 
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TIMEDWAIT 


TIMEDWAIT 

This macro waits for a period of time for an event or condition 
to occur. You can specify up to six instructions for this macro to 
execute in a loop to determine whether the event has occurred. 

This macro does not read the processor's clock. The interval it 
waits is approximate and depends upon the processor and the 
set of instructions you choose for testing to see if the condition 
exists. 

TIMEWAIT TIME, [INS1 ], [INS2], 
[INS3], - 

[INS4], [INS5], [INS6], 
[DONELBL], - 
[IMBEDLBL], [UBLBL] 


TIME 

The number of 10-microsecond intervals by which to multiply 
the processor-specific value in order to calculate the interval to 
wait. The processor-specific value is inversely proportional to 
the speed of the processor, but is never less than 1. 

If you do not specify any imbedded instructions, increase the 
value of TIME by 25 percent. 

If you specify imbedded instructions that take longer to execute 
than the average, such as the POLYD instruction, they will 
cause TIMEDWAIT to wait proportionally longer. 

[INS1 ] 

The first instruction in the loop. 

[INS2] 

The second instruction in the loop. 

[INS3] 

The third instruction in the loop. 

[INS4] 

The fourth instruction in the loop. 
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TIMEDWAIT 


[INS5] 

The fifth instruction in the loop. 

[INS6] 

The sixth instruction in the loop. 

[DONELBL] 

The label placed at the address of the instruction at the end of 
the TIMEDWAIT loop; imbedded instructions can pass control 
to this label in order to pass control to the instruction following 
the invocation of the TIMEDWAIT macro. 

[IMBEDLBL] 

The label placed at the first of the imbedded instructions; after 
executing a processor-specific delay, the macro passes control 
here to retest for the condition. 

[UBLBL] 

The label placed at the instruction that performs the processor- 
specific delay after each execution of the loop of imbedded 
instructions; imbedded instructions can pass control here 
in order to skip the execution of the rest of the imbedded 
instructions in a given execution of the imbedded loop. 

This macro returns a status code (success or failure) in RO. It 
destroys the contents of Rl, and preserves the contents of all 
other registers. 
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$VIELD 

This macro defines bit-fields whose names have the form 
mod$x_sym, where x can be V, S, or M. 

$VIELD MOD, INIBIT, FIELDS 

MOD 

The module in which this bit-field is defined; the prefix portion 
of the name of the symbols to be defined. 

INIBIT 

The bit within the field on which the positions of the bits to be 
defined are based. 

FIELDS 

One or more fields of the form <sym,[size=l],[mask]> , where 
these arguments are defined as follows: 


Argument 

Meaning 

sym 

The string appended to the string "mod$" to 
form the name of this bit-field. 

[size=1] 

The size, in bits, of this bit-field 

[mask] 

The character m if the value of the symbol is to 
be a bit-mask, blank otherwise 
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_VIELD 

This macro defines bit-fields whose names have the form mod_ 
x__sym, where x can be V, S, or M. 

_VIELD MOD, INIBIT, FIELDS 

MOD 

The module in which this bit-field is defined; the prefix portion 
of the name of the symbols to be defined. 

INIBIT 

The bit within the field on which the positions of the bits to be 
defined are based. 

FIELDS 

One or more fields of the form <sym,[size=l],[mask]>, where 
these arguments are defined as follows: 


Argument 

Meaning 

sym 

The string appended to the string "mod_" to 
form the name of this bit-field 

[size=1] 

The size, in bits, of this bit-field 

[mask] 

The character m if the value of the symbol is to 
be a bit-mask, blank otherwise 
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WFIKPCH 

This macro causes a process to wait for an interrupt from 
a device by calling IOC$WFIKPCH. The process retains 
ownership of the channel (the controller) while waiting. 

The waiting can be ended by the successful completion of a 
device operation, a device failure, or a timeout. When the 
interrupt occurs, control returns to the instruction following this 
macro. 

WFIKPCH EXCPT, [TIME 65536] 

EXCPT 

The name of a device-timeout-handling routine; the address 
of this routine must be within 65,536 bytes of the address at 
which this macro is invoked 

[TIME=65536] 

The number of seconds to wait for an interrupt before a device 
timeout is considered to exist 

When this macro is invoked, the following registers must 
contain the values listed. 


Register 

Contents 

R5 

The address of the UCB 

(SP) 

The IPL at which control is passed to the caller's 
caller 

4(SP) 

The address (in the caller's caller) at which to return 
control 


This macro destroys the contents of registers RO through R2. 
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WFIRLCH 

This macro causes a process to wait for an interrupt from 
a device by calling IOC$WFIRLCH. The process releases 
ownership of the channel (the controller) while waiting. 

The waiting can be ended by the successful completion of a 
device operation, a device failure, or a timeout. When the 
interrupt occurs, control returns to the instruction following this 
macro. 

WFIRLCH EXCPT, [TIME 65536] 

EXCPT 

The name of a device-timeout-handling routine; the address 
of this routine must be within 65,536 bytes of the address at 
which this macro is invoked 

[TIME=65536] 

The number of seconds to wait for an interrupt before a device 
timeout is considered to exist 

When this macro is invoked, the following registers must 
contain the values listed. 


Register 

Contents 

R5 

The address of the UCB 

(SP) 

The IPL at which control is passed to the caller's 
caller 

4(SP) 

The address (in the caller's caller) at which to return 
control 


This macro destroys the contents of registers RO through R2. 
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This appendix describes the VAX/VMS operating system 
routines that are used by device drivers. The information given 
in this section follows the conventions listed below: 

• Fields used for both input and output are not specified. 

• Registers are assumed preserved unless otherwise specified. 

• IPL at execution refers to the interrupt priority level at which 
the routine executes, not the IPL at which it is called. 
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COM$DELATTNAST 


COM$DELATTNAST 


Module: COMDRVSUB 

Driver fork processes call this routine to deliver all the AST- 
control blocks linked to the specified AST list. 

Input 


Registers 

R4 

R5 

Fields 


Contents 

Address of specified listhead 
Address of the unit-control block 

Contents 


IPL At execution: caller's IPL 

This routine removes all AST blocks from the specified list and 
schedules an IPL$_QUEUEAST level fork process to queue 
each AST to its process. 

Output 

Registers Contents 

Fields Contents 

Specified listhead 0 

IPL At exit: caller's IPL 
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COM$DRVDEALMEM 


COM$DRVDEALMEM 

Module: COMDRVSUB 

Drivers use this routine to deallocate system dynamic memory. 
COM$DRVDEALMEM can be called from any interrupt priority 
level. 

Input 

Registers Contents 

RO Address of the block to be deallocated 

Fields Contents 

IRP$W_SIZE Size of the block in bytes 

IPL At execution: caller's IPL and IPL$_QUEUEAST 

If the block size is smaller than 24 bytes or the block is not 
properly aligned, a system bugcheck occurs. This routine also 
calls S(ZH$RAVAIL to mark the resource free. 

IPL At exit: caller's IPL 
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CGM$FLUSHATTNS 


COM$FLUSHATTNS 

Module: COMDRVSUB 


Driver FDT and fork routines call this routine to flush an 
attention AST list. Drivers use this routine during cancel I/O 
operations. 


Input 

Registers 

R4 

R5 

R6 

R7 

Fields 

UCB$B_DIPL 

PCB$I_PID 

PCB$W_ASTCNT 


Contents 

Address of the current PCB 

Address of the UCB 

Number of the assigned channel 

Address of the AST-control block listhead 

Contents 

Device IPL 

Process's ID 

ASTs remaining in quota 


IPL At execution: device IPL (UCB$B_DIPL) 


COM$FLUSHATTNS locates all the control blocks whose 
channel number and process identification match those specified 
as input to the routine, removes them from the specified list 
and deallocates them. This routine exits by returning to its 
caller. 


Output 

Registers 

RO 

R1 

R2 

R7 

Fields 

PCB$ W_AST CNT 
Specified listhead 


Contents 

SS$_NORMAL 

Destroyed 

Destroyed 

Destroyed 

Contents 

Number of ACBs flushed (added to 
previous contents) 

Updated 


IPL At exit: caller's IPL 
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COM$POST 


Module: COMDRVSUB 


Drivers call this routine after they have completed all device¬ 
dependent I/O postprocessing for an I/O request. This routine 
inserts the I/O-request packet into the I/O postprocessing 
queue and returns to the driver fork process. COM$POST 
operates independently of the device unit; it does not attempt 
to dequeue another packet nor does it change the busy status of 
the device. 

Drivers can use this routine to complete the processing of 
I/O-request packets initiated by the routine EXE$ALTQUEPKT. 


Input 

Registers 

R3 

R5 

Fields 

IRP$I_MEDIA 


Contents 

Address of the I/O-request packet 
Address of the unit-control block 

Contents 

Data to be copied into the 1/0-status 
block 

Data to be copied to the 1/0-status block 


IRP$I_MEDIA+4 


IPL At execution: caller's IPL (driver fork level or above) 

This routine places the I/O-request packet into the queue 
headed by IOC$GL_PSBL. 

Output 


Registers 
RO - R1 
Fields 

UCB$I_OPCNT 


Contents 

Destroyed 

Contents 


Incremented by 1 


IPL At exit: caller's IPL 
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COM$SET ATTN AST 


COM$SETATTNAST 

Module: COMDRVSUB 

Driver FDT routines call this routine to enable or disable 
attention ASTs, depending on the contents of the queue-I/O 
parameter PI. To enable an AST, PI contains the address of 
an AST routine. The routine allocates a control block that can 
double as an AST-control block when the AST is delivered. 

This control block contains the following information: 

• The address of the specified AST routine 

• The specified AST parameter 

• The specified access mode 

• The channel number 

• The process identification of the requesting process 

COM$SETATTNAST links the control block to the start of 
the specified linked list of AST-control blocks located in the 
unit-control block's extension area. 


If PI is clear, the routine disables ASTs by searching through 
the linked list, extracting each entry, and deallocating it. 

Input 

Registers Contents 

R3 Address of the IRP 

R4 Address of the current PCB 

R5 Address of the UCB 

R6 Address of the assigned channel's 

channel-control block 

R7 Address of the specified AST-control 

block listhead 

AP Address of the QIO parameter list 
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COM$SETATTNAST 


Fields 


Contents 


IRP$W_CHAN 
UCB$B_DIPL 
PCB$ W_AST CNT 

PCB$I_PID 

O(AP) 

4(AP) 

8(AP) 


I/O request channel number 
Device IPL 

Number of ASTs remaining in process 
quota 

Process identification 
Process AST address 
AST parameter 
Access mode for AST 


IPL At execution: caller's IPL and device IPL 


If the process exceeds buffered I/O or AST quotas, or if there 
is no memory available to allocate an AST-control block, this 
routine transfers control to EXE$ABORTIO with error status. 

If PI is clear, the routine transfers control to 
COM$FLUSHATTNS to remove the identified AST-control 
block. 


This routine exits to its caller. 


Output 

Registers 

RO 

R1 - R2 

R3 

R5 

R6 - R8 

Fields 

PCB$ W_AST CNT 
Specified listhead 


Contents 


SS$_NORMAL (success) SS$_EXQUOTA 
SS$_INSFMEM 

Destroyed 
Address of the IRP 
Address of the UCB 
Destroyed 
Contents 
Decreased by 1 
Updated 


IPL At exit: caller's IPL 
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ERL$DEVICERR 


ERL$DEVICERR 


Module: ERRORLOG 


Logs a controller and/or device error. This routine allocates 
an error message buffer and writes data from the I/O-request 
packet and unit-control block. It also calls the driver register 
dump routine for device registers. 


Input 

Registers 

R5 


Contents 

Address of unit-control block 


ERL$DEVICERR sets the error type code to device error. This 
routine uses fields in the UCB, DDB, DDT, and I/O-request 
packet. It also assumes that the driver contains a register dump 
routine. It uses the DDT to calculate the address of the register 
dump routine and then calls it. 

If you do not specify a dump routine in the DDTAB macro 
invocation, DDTAB supplies the address of IOC$RETURN. 
IOC$RETURN simply returns; it is a NOP. 


Output 

Registers 


Contents 


Fields 

UCB$I_EMB 

UCB$I_STS 


Contents 

Address of the error message buffer 
Shows error log in progress 
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ERL$DEVICTMO 


ERL$DEVICTMO 

Module: ERRORLOG 

Logs a device timeout. This routine performs the 
same functions and uses the same input and output as 
ERL$DEVICERR with one exception: the error type code is 
device timeout. 
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EXE$ABORTIO 

Module: SYSQIOREQ 

FDT routines jump to this routine to finish an I/O operation 
without returning final I/O status in the IOSB. This routine 
zeroes the IOSB field of the I/O-request packet, clears a bit to 
prevent a user mode AST, and inserts the I/O-request packet in 
the I/O postprocessing queue. 

Input 
Registers 
RO 

R3 
R4 
R5 

Fields 

ACB$V_QUOTA (in 
IRP$B_RMOD) 

IPL At execution: IPL$_ASTDEL 


Contents 

First longword of status for l/O-status 
block 

Address of I/O-request packet 
Address of current PCB 
Address of UCB 

Contents 

Set to 1 (when an AST is specified) 


Output 

Registers 

None written 

Fields 

ACB$V_QUOTA (in 
IRP$B_RMOD) 

IRP$I_IOSB 

PCB$W_ASTCNT 


Contents 

Contents 

Cleared to zero (if field previously set) 
Zero 

Incremented if ACB$V_QUOTA was set 


EXE$ABORTIO places the I/O-reguest packet into the I/O 
postprocessing queue headed by IOC$GL_PSBL. 

IPL At exit: 0 (normal process IPL) 
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EXE$ALLOCBUF 

Module: MEMORYALC 

FDT routines call this routine to allocate a buffer for a buffered 
I/O operation from the nonpaged system pool. This routine can 
place the process in a resource wait state if sufficient memory is 
not available, and the process has resource wait mode enabled. 
The caller must adjust process quotas. 


Input 


Registers 

R1 

R4 

Fields 

PCB$V_SSRWAIT 

Contents 

Size of requested buffer in bytes 

Address of current PCB 

Contents 

One or zero. Determines whether process 
should wait, if no memory available for 
requested buffer. If this field is set, 
resource wait mode is disabled. 


IPL At execution: caller's IPL, IPL 11, and IPL$_SYNCH 


Output 


Registers 

RO 

R1 

Contents 

SS$_NORMAL (success) SS$_INSFMEM 

Size of allocated buffer (requested size is 
rounded up to next 16-byte multiple) 

R2 

R3 

Fields 

IRP$W_SIZE (in 
allocated buffer) 

IRP$B_TYPE (in 
allocated buffer) 

Address of allocated buffer 

Destroyed 

Contents 

Buffer size in bytes 

DYN$C_BUFIO 


IPL At exit: IPL$_ASTDEL 
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EXE$ALLOCIRP 

Module: MEMORYALC 

This routine allocates an I/O-request packet from nonpaged 
dynamic memory. It performs the same functions and has the 
same input and output as EXE$ALLOCBUF, with the following 
exceptions: 

• The caller does not specify a buffer size. 

• The allocated buffer is IRP$C_LENGTH bytes long. 

• The buffer size is set to IRP$C_LENGTH. 

• The buffer type is set to DYN$C_IRP. 
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EXE$ALONONPAGED 

Module: MEMORYALC 

Driver fork processes use this routine to allocate a block of 
memory from the nonpaged system pool. 

The block header is not initialized. 


Input 


Registers 

R1 

Fields 

Contents 

Requested block size in bytes 

Contents 

None 

— 


IPL At execution: caller's IPL (must not fall below IPL11) and IPL 


11 


Output 


Registers 

RO 

R1 

Contents 

Status code (0 or 1) 

Size of allocated buffer (requested size 
rounded up to next 16-byte multiple) 

R2 

R3 

Fields 

Address of allocated block 

Destroyed 

Contents 


IPL At exit: caller's IPL 
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EXE$ALOPHYCNTG 

Module: MEMORYALC 

Driver fork processes use this routine to allocate a physically 
contiguous block of memory. Note that the number of SPTs 
available depends on the value of system parameter SPTREQ. 

Memory allocated by this routine must not be deallocated. 

Input 

Registers Contents 

R1 The number of physically contiguous 

pages to allocate 

Fields Contents 

None — 

IPL At execution: caller's IPL (must be IPL$_SYNCH) 

Output 

Registers Contents 

RO Status code (SUCCESS, ISSFMEM, or 

INSFSPTS) 

R2 System virtual address of allocated block, 

if the allocation succeeds 

All other registers are preserved. 

Fields Contents 


IPL At exit: caller's IPL 
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EXE$ALTQUEPKT 


Module: SYSQIOREQ 


Driver FDT routines and fork processes call this routine to send 
an I/O-request packet to a driver's alternate start-I/O routine 
so that it bypasses the I/O request queue for the device's unit- 
control block. EXE$ALTQUEPKT passes the address of the 
I/O-request packet to the driver without regard for the status of 
the device unit. 


Input 

Registers 

R3 

R5 

Fields 


Contents 

Address of the I/O-request packet 
Address of the unit-control block 

Contents 


DDT$I_ALTSTART Address of the alternate start-I/O routine 


UCB$B_FIPL 

UCB$I_DDB 

DDB$I_DDT 


Driver fork IPL 

Address of unit's DDB 

Address of the driver-dispatch table 


IPL At execution: UCB$I_FIPL 

EXE$ALTQUEPKT calls the alternate start-I/O routine and 
returns to its caller. 

Output 


Registers 
RO - R5 
Fields 


Contents 

Destroyed 

Contents 


IPL At exit: caller's IPL 
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EXE$BUFFRQUOTA 

Module: EXSUBROUT 

FDT routines call this routine to determine whether a process's 
buffered byte count quota usage permits the process to be 
granted additional buffered I/O. This routine can place the 
process in a resource wait state if quota usage is too large, and 
the process has resource wait mode enabled. 


Input 

Registers 

R1 

R4 

Fields 

PCB$V_SSRWAIT 

IOC$GW_MAXBUF 

JIB$I_BYTLM 

JIB$I_BYTCNT 


Contents 

Number of requested bytes 
Address of PCB 

Contents 

When process exceeds quota, determines 
whether process should wait. If this field 
is set, resource wait mode is disabled. 

Maximum number of buffered I/O bytes 
that system allows to any process 

Process's byte count limit 
Process's byte count usage quota 


IPL At execution: caller's IPL and IPL$_SYNCH 


Output 

Registers 

RO 

R2 - R3 

Fields 


Contents 

SS$_NORMAL (success) SS$_EXQUOTA 
Destroyed 

Contents 


IPL At exit: IPL$_ASTDEL 
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EXE$BUFQUOPRC 

Module: EXSUBROUT 

EXE$BUFQUOPRC performs the same function and has the 
same input and output as EXE$BUFFRQUOTA with the 
following exception: EXE$BUFQUOPRC does not check the 
field IOC$GW_MAXBUF. 
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EXE$DEANONPAGED 


EXE$DEANONPAGED 

Module: MEMORYALC 

Deallocates a block of memory to the nonpaged system pool. 

This routine performs the same functions and has the same 
input and output as the routine COM$DRVDEALMEM, with 
the following exceptions: 

• R3 is destroyed 

• The caller's IPL must be at IPL$__QUEUEAST or lower 
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EXE$FINISHIO 

Module: SYSQIOREQ 

FDT routines transfer control to this routine to finish an I/O 
operation and return a quadword of final I/O status to the 
requesting process. This routine writes final I/O status into the 
I/O-request packet and inserts the I/O-request packet in the 
I/O postprocessing queue. 


Input 

Registers 

RO 

R1 

R3 

R4 

R5 


Contents 

First longword of status for the l/O-status 
block 

Second longword of status for the 
l/O-status block 

Address of the I/O-request packet 

Address of the current process-control 
block 

Address of the UCB 


Output 

Registers Contents 

RO SS$_NORMAL 

Fields Contents 

IRP$I_MEDIA First longword of I/O status (RO) 

IRP$I_MEDIA+4 Second longword of I/O status (R1) 

UCB$I_OPCNT Incremented by 1 


This routine places the I/O-request packet into the I/O 
postprocessing queue headed by IOC$GL_JPSBL. 
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EXE$FINISHIOC 

Module: SYSQIOREQ 

This routine performs the same functions and has the same 
input and output as EXE$FINISHIO with the following 
exception: EXE$FINISHIOC clears the contents of R1 before 
storing RO and R1 in the I/O-request packet. 
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EXE$FORK 

Module: FORKCNTRL 

This routine performs the same functions as EXE$IOFORK 
except that this routine does not disable timeouts by clearing 
UCB$V_TIM in the UCB$L_STS field of the unit-control block. 
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EXE$INSERTIRP 

Module: SYSQIOREQ 

Inserts an I/O-request packet according to the base priority of 
the I/O-request packet's originating process into the pending- 
l/O queue of a unit-control block. 


Input 

Registers 

R2 

R3 

Fields 


Contents 

Address of the I/O queue list head for the 
device 

Address of the I/O-request packet 

Contents 


IPL At execution: caller's IPL (fork level or higher) 

Output 

Registers Contents 

R1 Destroyed 

This routine places the I/O-request packet in the queue and 
sets the Z condition code in the PSL as follows: 

1 indicates that the entry is first in the queue. 

0 indicates that at least one entry was already in the queue. 

IPL At exit: caller's IPL 
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EXE$INSIOQ 

Module: SYSQIOREQ 

Examines the unit-control block. If the device is idle, this 
routine calls IOC$INITIATE; if the device is busy, it calls 
EXE$INSERTIRP. 


Input 

Registers 

R3 

R5 

Fields 

UCB$B_FIPL 

UCB$V_BSY (in 
UCB$I_STS) 

UCB$I_IOQFL 


Contents 

Address of the l/O-request packet 
Address of the UCB 
Contents 
Driver fork IPL 

Determines whether device is busy 
Address of device I/O queue listhead 


IPL At execution: driver fork level 


Output 

Registers Contents 

RO - R2 Destroyed 

Additional registers used by the driver start-l/O routine will 
be destroyed if the start-l/O routine is called. 

Fields Contents 

UCB$V_BSY (in Set to 1 

UCB$I_STS) 

IPL At exit: original IPL 
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EXE$INSTIMQ 

Module: EXESUBROUT 

Inserts a timer queue element into the timer queue. Elements 
are ordered according to expiration time with those elements 
closest to due time taking priority. 


Input 


Registers 

RO, R1 

Contents 

Quadword expiration time for new 
element 

R5 

Address of timer element to be queued 


IPL At execution: IPL$_TIMER 


Output 


Registers 

R2 - R3 

Contents 

Destroyed 


IPL At exit: IPL$_TIMER 
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EXE$IOFORK 

Module: FORKCNTRL 

Saves the contents of R3 and R4 in the fork block specified by 
R5. This routine pops the return PC off the top of stack and 
saves the PC value in the fork block. It inserts the fork block 
address into the fork queue corresponding to the IPL stored in 
the fork block. 


Input 

Registers 

R5 

O(SP) 

4(SP) 

Fields 

FKB$B_FIPL (in fork 
block) 


Contents 

Address of the fork block (usually the 
UCB) 

Return address of caller 
Return address of caller's caller 

Contents 
Fork IPL 


IPL At execution: caller's IPL 


Output 

Registers 

R3 

R4 

Fields 

UCB$V_TIM (in 
UCB$I_STS) 

FKB$I_FR3 (in UCB) 

FKB$I_FR4 (in UCB) 

FKB$I_FPC (in UCB) 


Contents 

Destroyed 

FKB$B_FIPL 

Contents 

0 

R3 

R4 

O(SP) 


The routine queues the UCB address to the list headed by 
SWI$GL_FQFL. If the queue is empty, requests a software 
interrupt at fork IPL. 

IPL At exit: caller's IPL 
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EXE$LCLDSKVALID 

Module: SYSQIOFDT 

A disk driver's FDT routines call this routine to process a 
request for an IO$_PACKACK, IO$_AVAILABLE, or IO$_ 
UNLOAD on a local disk, and to queue the IRP to the device's 
UCB for driver processing, if needed. This must be the last FDT 
routine called during preprocessing of these requests. 

If the function is IO$_PACKACK and UCB$V_LCL_VALID 
is not set, this routine sets UCB$V_LCL_VALID, increments 
UCB$B_ONLCNT, and queues the IRP to the UCB for driver 
processing by branching to EXE$QIODRVPKT. If UCB$V_ 

LCL—VALID is set, this routine calls EXE$FINISHIO. 

If the function is IO$_UNLOAD or IO$—AVAILABLE and 
UCB$V—LCL—VALID is set, this routine clears UCB$V_LCL— 
VALID, decrements the field UCB$B_ONLCNT, and queues the 
IRP to the UCB for driver processing. If UCB$V_LCL-VALID 
is not set, this routine calls EXE$FINISHIO. 


Input 

Registers 

R3 

R5 

R7 

Fields 

UCB$V_LCI_VALID 

(in UCB$I_STS) 


Contents 

Address of the IRP 
Address of the UCB 

The number of the bit that the l/O- 
function code represents 

Contents 

If set, the volume is already valid. If 
not set, the drive is already unloaded or 
available 


IPL At execution: caller's IPL (should be IPL$_ASTDEL) 

Output 

Registers Contents 

R3 Destroyed 

R4 FKB$B_FIPL 
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EXE$LCLDSKVALID 


Fields 

Contents 

UCB$V_LCI_VALID 

If the requested function is 

IO$_PACKACK, this bit is set 

(in UCB$I_STS); if the requested function 

is IO$_UNLOAD or IO$_AVAILABLE, this 
bit is cleared 

UCBSB—ONLCNT 

If the function is IO$_PACKACK and, on 

entry to this routine, UCB$V_LCI_VALID 

was not set, this field is incremented; 
if the function is IO$_UNLOAD or IO$_ 
AVAILABLE and, on entry to this routine, 

UCB$V_LCI_VALID was set, this field is 

decremented 


Because this routine passes control to EXESQIODRVPKT if 
processing is required by the driver, or to EXE$FINISHIO if no 
further processing is required, these outputs are not returned 
to the caller of this routine. 

IPL This routine raises IPL to IPL$_SYNCH. 
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EXE$MODIFY 


Module: SYSQIOFDT 


FDT routines transfer control to this device-independent routine 
that validates and readies a user buffer for a DMA read/write 
operation. Use EXE$MODIFY instead of EXE$READ when you 
wish your driver to read and write to a buffer. EXE$MODIFY 
disables a paging mechanism used during write-only operations. 

This routine performs the following functions: 

• Translates read-logical functions to read-physical functions 

• Transfers queue-I/O parameters to the I/O-request packet 

• Verifies that the caller has access to the specified buffer 

• Locks the buffer's pages into physical memory. If a page 
fault occurs during this step, the routine returns control to 
the Queue-I/O-Request system service, which repeats the 
request. 


Input 



Registers 


Contents 

Address of the l/O-request packet 
Address of the current PCB 

Address of the UCB assigned to the 
device unit 

Address of the CCB for the channel 
assigned to the device unit 

Bit number of the l/O-function code 
FDT entry address 

Address of the first function-dependent 
QIO parameter (PI) 

Contents 

Virtual address of buffer (PI) 

Number of bytes in transfer (P2) 
Carriage control byte (P4) 
l/O-function code 


R3 

R4 

R5 


R6 


R7 

R8 

AP 


Fields 

O(AP) 

4(AP) 

12(AP) 


IRP$W_FUNC 


IPL At execution: caller's IPL (IPL$_ASTDEL) 
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EXE$MODIFY 


If this routine completes successfully, it transfers control to 
EXE$QIODRVPKT. If EXE$MODIFY fails, it transfers control to 
EXE$ABORTIO. 

EXE$MODIFY does not check for zero-length transfers and 
will queue an IRP that specifies a zero-length buffer to the 
UCB. The driver start I/O routine should check for zero length 
buffers to avoid mapping them to UNIBUS or MASSBUS space, 
because the attempted mapping causes a system failure. 


Output 


Registers 
RO - R2 
Fields 

IRP$B_CARCON 

IRP$V_FUNC (in 
IRP$W_STS) 

IRP$I_SVAPTE 


Contents 

Destroyed 

Contents 

P4 


Address of page-table entry that maps 
the first page of the buffer 

Size of the transfer in bytes 


Set to 1 (indicates a read function) 


IRP$W_BCNT 


IPL At exit: caller's IPL 
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EXE$MODIFYLOCK 

Module: SYSQIOFDT 

FDT routines call EXE$MODIFYLOCK to perform buffer 
processing on a DMA transfer. This routine 

• Determines whether the caller has write access to the buffer 


• Locks the buffer's pages into memory. If a page fault occurs 
during this process, the routine returns control to the Queue 
I/O Request system service, which resubmits the request. 

Use EXE$MODIFYLOCK instead of EXE$READLOCK 
when you expect your driver to read and write to a buffer. 
EXE$MODIFYLOCK disables a paging mechanism used in 
write-only operations. 


Input 

Registers 

RO 

R1 

R3 

R4 

R6 

Fields 


Contents 

Starting address of buffer 

Size of transfer in bytes 

Address of the l/O-request packet 

Address of current PCB 

Address of the CCB 

Contents 


IPL At execution: caller's IPL (IPL$_ASTDEL) 

If EXE$MODIFYLOCK fails, it transfers control to 
EXE$ABORTIO. If the routine completes successfully, control is 
returned to its caller. 


Output 

Registers 

RO 

R1 

R2 

R3 


Contents 

SS$_NORMAL 

Address of the PTE that maps the first 
page of the buffer 

Destroyed 
Address of the IRP 
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EXE$MODIFYLOCK 



Contents 

Address of the PTE that maps the first 
page of the buffer 

Size of the transfer in bytes 
A value of 1 (indicating a read function) 

IPL At exit: caller's IPL 



Fields 

IRP$I_SVAPTE 

IRP$W_BCNT 

IRP$V_FUNC (in 
IRP$W_STS) 
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EXE$MODIFYLOCKR 

Module: SYSQIOFDT 

This routine determines whether a process has write access 
to the buffer pages it requested, then, if access is permitted, it 
locks the pages into memory. If the access-checking or page¬ 
locking procedure fails, the routine calls the driver to clean up 
QIO bookkeeping. Drivers typically use EXE$MODIFYLOCKR 
when they must lock multiple areas into memory for one I/O 
request, and then need to unlock previously locked areas after 
an I/O request is aborted. 


Input 

Registers 

RO 

R1 

R3 

R4 

R6 

Fields 


Contents 

Starting address of buffer 
Length of the buffer in bytes 
Address of the IRP 

Address of the current process's PCB 
Address of the channel-control block 

Contents 


EXE$MODIFYLOCKR can fail for a number of reasons: 

• The buffer-access check fails. In this case, the routine 
returns SS$_ACCVIO to the driver in RO. 

• The caller process has an insufficient working set limit to 
lock all the buffer pages into memory. The routine returns 
SS$_INSFWSL in RO. 

• A page fault occurs while the routine is locking pages into 
memory. The status returned in RO in this case is zero. 

If any of the above errors occur, the routine calls back the 
driver as a coroutine with error status in RO and all other 
registers preserved. 

The driver performs necessary queue-I/O cleanup. It carries 
out any procedures that the system does not perform as part of 
the normal queue-I/O request's abortion processing. 

The driver must preserve all registers, including RO and Rl. 
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EXE$MODIFYLOCKR 


When the driver returns by executing an RSB instruction, 
EXE$MODIFYLOCKR aborts the I/O request if RO contains an 
error status, then performs processing that results in the I/O 
request's being resubmitted to the driver. For example: 

JSB G~EXE$MODIFYLOCKR 

BLBS BUF_LOCK_OK 

BUF_LOCK_FAIL: 

<clean up this QIO bookkeeping> 

RSB 

BUF_LOCK_OK: 

<continue this QIO> 


If the subroutine is successful, it returns control to its caller. 


Output 

Registers 

RO 

R1 

R2 

R3 

Fields 

IRP$I_SVAPTE 

IRP$W_BCNT 

IRP$M_FUNC (in 
IRP$W_FUNC) 


Contents 

SS$_NORMAL (1) 

Address of the PTE that maps the first 
page of the buffer 

Function indicator (set to 1) 

Address of the IRP 
Contents 

Address of the PTE that maps the first 
page of the buffer 

Size of the transfer in bytes 
Set to 1 


IPL At exit: caller's IPL 
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EXE$ONEPARM 

Module: SYSQIOFDT 

Device-independent FDT routine that copies a single 
QIO parameter into the I/O-request packet and calls 
EXE$QIODRVPKT. 


Input 


Registers 

R3 

Contents 

Address of the l/O-request packet for the 
current I/O request 

R4 

Address of the process-control block of 
the current process 

R5 

Address of the unit-control block of the 
device assigned to the user-specified 
process I/O channel 

R6 

Address of the channel-control block that 
describes the user-specified process I/O 
channel 

R7 

Bit number of the user-specified l/O- 
function code 

R8 

AP 

Address of FDT entry 

Address of the first function-dependent 
parameter specified in the user's request 

Fields 

Contents 

Output 


Registers 

Contents 

Fields 

IRP$I_MEDIA (of IRP) 

Contents 

PI 


IPL At exit: caller's IPL 

This routine exits to EXE$QIODRVPKT. 

Chapter 8 provides more information about this routine. 
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EXE$QIODRVPKT 

Module: SYSQIOREQ 

FDT routines call this routine to send an IRP to a driver start- 
I/O routine. This routine calls EXE$INSIOQ and then transfers 
control to EXE$QIORETURN. 


Input 

Registers 

R3 

R4 

R5 

Fields 

UCB$B_FIPL 

UCB$V_BSY (in 
UCB$I_STS) 

UCB$I_IOQFL 


Contents 

Address of the l/O-request packet 

Address of the process-control block 

Address of the unit-control block 

Contents 

Driver fork IPL 

Unit busy flag 

Address of unit I/O queue listhead 
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EXE$QIORETURN 

Module: SYSQIOREQ 

Sets a success status code in RO, lowers IPL to 0, and returns to 
the system service dispatcher. 

Output 

Registers Contents 

RO SS$_NORMAL 

IPL At exit: 0 

This routine returns by issuing a RET instruction. 
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EXE$READ 

Module: SYSQIOFDT 

Device-independent FDT routine that validates and readies a 
user buffer for a DMA read operation. This routine performs 
the same functions and has the same input and output as 
EXE$MODIFY, with a single exception noted in the description 
of EXE$MODIFY. 
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EXE$READCHK 

Module: SYSQIOFDT 

Checks pages for write accessibility by a process. This routine 
writes the total byte count of a transfer into the I/O-request 
packet. 

If pages do not allow write access, the routine transfers control 
to EXE$ABORTIO, which terminates the request with access 
violation status. If EXE$READCHK completes successfully, 
control returns to its caller. 

Input 
Registers 
RO 
R1 
R3 

Fields 


Contents 

Address of buffer 

Size of the transfer in bytes 

Address of the l/O-request packet 

Contents 


IPL At execution: caller's IPL 


Output 

Registers 

RO 

R1 

R2 

R3 

Fields 

IRP$W_BCNT 

IRP$V_FUNC (in 
IRP$W_STS) 


Contents 

Address of buffer (success) 

Size of transfer in bytes 
Value of 1 (to indicate a read) 
Address of IRP 

Contents 

Size of transfer in bytes 

Value of 1 (indicates a read function) 


IPL At exit: caller's IPL 
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EXE$READCHKR 

Module: SYSQIOFDT 

This routine performs the same function as EXE$READCHK, 
except that, on error, it calls the driver FDT routine back as a 
coroutine to clean up QIO bookkeeping. See the description 
of error procedures in EXE$MODIFYLOCKR for further 
information. 
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EXE$READLOCK 

Module: SYSQIOFDT 

FDT routines call this routine to check buffer accessibility and 
lock the user buffer in memory for a DMA read transfer. This 
routine performs the same functions and has the same input 
and output as EXE$MODIFYLOCK, except that it is used when 
the driver performs only a read function. 
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EXE$READLOCKR 

Module: SYSQIOFDT 

This subroutine determines whether a process has write 
access to requested buffer pages and, if access is permitted, 
it locks those pages into memory. EXE$READLOCKR performs 
the same functions and has the same input and output as 
EXE$MODIFYLOCKR. 
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EXE$SENSEMODE 

Module: SYSQIOFDT 

Device-independent FDT routine that copies device-dependent 
characteristics from the device's UCB into Rl. This routine 
writes a success code into RO and transfers control to 
EXE$FINISHIO. 


Input 


Registers 

R3 

Contents 

Address of the l/O-request packet for the 
current I/O request 

R4 

Address of the PCB of the current 
process 

R5 

Address of the UCB of the device 
assigned to the user-specified process 

I/O channel 

R6 

Address of the CCB that describes the 
user-specified process I/O channel 

R7 

Bit number of the user-specified l/O- 
function code 

R8 

Address of function-decision table 
dispatch 

AP 

Address of the first function-dependent 
parameter specified in the user's request 

Fields 

UCB$I_DEVDEPEND 

Contents 

Device-dependent status 


IPL At execution: caller's IPL 
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Output 
Registers 
RO 
R1 

Fields 


Contents 

SS$_NORMAL 

Device-dependent characteristics copied 
from UCB$I_DEVDEPEND 

Contents 


IPL At exit: caller's IPL 

This routine exits to EXE$FINISHIO. 

For additional information, refer to Chapter 8. 
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EXE$SETCHAR 

Module: SYSQIOFDT 

Device-independent FDT routine that writes a quadword whose 
address is QIO parameter PI into the device's unit-control 
block. Writes a success code into RO and transfers control to 
EXE$FINISHIO. 


Input 

Registers 

R3 

R4 

R5 

R6 

R7 

R8 

AP 

Fields 

O(AP) 


Contents 

Address of the IRP for the current I/O 
request 

Address of the current PCB 

Address of the UCB of the assigned 
device unit 

Address of the CCB that describes the 
specified process I/O channel 

Bit number of the l/O-function code 
Address of the FDT dispatcher 

Address of the first function-dependent 
QIO parameter 

Contents 

Address of new device characteristics 

(PI) 


IPL At execution: caller's IPL 


If this routine fails because the user lacks read access to the 
characteristics quadword, control transfers to EXE$ABORTIO 
with access violation status. 

If EXE$SETCHAR completes successfully, it transfers control to 
EXE$FINISHIO. 

Output 

Registers Contents 

RO SS$_NORMAL (success) SS$_ACCVIO 

(failure) 
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Fields 

UCB$B_DEVCLASS 
UCB$B_DEVTYPE 
UCB$W_DEVBUFSIZ 
UCB$I_DEVDEPEND 

Contents 

Byte 0 of quadword 

Byte 1 of quadword 

Bytes 2 and 3 of quadword 

Bytes 4 through 7 of quadword 


IPL At exit: caller's IPL 

Refer to Chapter 8 for additional information on this routine. 
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EXE$SETMODE 

Module: SYSQIOFDT 

Device-independent FDT routine that writes a quadword whose 
address is a QIO parameter into the I/O-request packet and 
calls EXE$QIODRVPKT. 


Input 


Registers 

R3 

Contents 

Address of the l/O-request packet for the 
current I/O request 

R4 

Address of the PCB of the current 
process 

R5 

Address of the UCB of the device 
assigned to the user-specified process 

I/O channel 

R6 

Address of the CCB that describes the 
user-specified process I/O channel 

R7 

R8 

AP 

Bit number of the l/O-function code 
Address of the FDT entry 

Address of the first function-dependent 
QIO parameter 

Fields 

Contents 

PO(AP) 

Address of a quadword of device 
characteristics 


IPL At execution: caller's IPL 

If the user lacks read access to the device characteristics 
quadword, the routine transfers control to EXE$ABORTIO 
with access violation status. If EXE$SETMODE completes 
successfully, it normally exits to EXE$QIODRVPKT. 


Output 


Registers 

RO 

Contents 

SSS—NORMAL (success) SS$_ACCVIO 
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EXE$SETMODE 


Fields Contents 

IRP$I—MEDIA First longword of device characteristics 

quadword 

IRP$I_MEDIA+4 Second longword of device characteristics 

quadword 

IPL At exit: caller's IPL 

For more information about this routine, refer to Chapter 8. 
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EXE$SNDEVMSG 

Module: MBDRIVER 

Driver fork processes call this routine to send messages to 
system processes such as OPCOM. This routine constructs a 
message on the stack and calls EXE$WRTMAILBOX to send the 
message to a mailbox. 


Input 

Registers 

R3 

R4 

R5 

Fields 

UCB$W_INIT 
UCB$I_DDB 

DDB$T_NAME 
Mailbox UCB fields 


Contents 

Address of the mailbox UCB 

Message type 

Address of the UCB 

Contents 

Device unit number 

Address of device DDB 

Device controller name 


IPL At execution: caller's IPL (must be at or below IPL$_ 
MAILBOX) 

This routine can fail for one of the following reasons: 

• The message is too large for the mailbox. 

• The message mailbox is full of messages. 

• The system is unable to allocate memory for the message. 

• The caller lacks privilege to write to the mailbox. 

If any of the above conditions occur, EXE$SNDEVMSG returns 
error status to the caller. 


If EXE$SNDEVMSG completes successfully, it exits with an 
RSB instruction. 
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Output 

Registers 

RO 


Contents 

SS$_NORMAL (success) 


SS$_MBTOOSML (message too large 
for mailbox) SS$_MBFULL (mailbox full 
of messages) SS$_INSFMEM (memory 
allocation problem) SS$_NOPRIV (no 
owner write access) 


R1-R4 

Fields 


Destroyed 

Contents 


IPL At exit: caller's IPL 
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EXE$WRITE 

Module: SYSQIOFDT 

Device-independent FDT routine that validates and readies a 
user buffer for a DMA write operation. This routine performs 
the same steps as EXE$MODIFY, and has the same input and 
output. 
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EXE$WRITECHK 

Module: SYSQIOFDT 

Checks pages for read accessibility by a process and writes the 
total byte count of a transfer into the I/O-request packet. If 
pages do not allow read access, the routine transfers control 
to EXE$ABORTIO, which terminates the request with access- 
violation status. If EXE$WRITECHK completes successfully, it 
returns to its caller. 


Input 


Registers 

RO 

R1 

R3 

Contents 

Address of buffer 

Size of the transfer in bytes 

Address of the l/O-request packet 


IPL At execution: caller's IPL 


Output 


Registers 

RO 

R1 

R2 

R3 

Fields 

IRP$W_BCNT 

Contents 

Buffer address (success) 

Size of the transfer in bytes 

Cleared (indicates a write function) 
Address of the I/O-request packet 

Contents 

Contains transfer size in bytes 


IPL At exit: caller's IPL 
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EXE$WRITECHKR 

Module: SYSQIOFDT 

This routine performs the same functions as EXE$WRITECHK, 
except that, on error, it calls the driver FDT routine back as a 
coroutine to clean up QIO bookkeeping. 

See the description of error procedures in EXE$MODIFYLOCKR 
for more information about coroutine cleanup. 
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EXE$WRITELOCK 

Module: SYSQIOFDT 

FDT routines call this routine to determine whether the caller 
has read access to the buffer and to lock the buffer in memory 
for a DMA write transfer. 


Input 


Registers 

RO 

R1 

R3 

R4 

R6 

Fields 

Contents 

Starting address of I/O buffer 

Length of transfer in bytes 

Address of the l/O-request packet 

Address of the PCB 

Address of the CCB 

Contents 


IPL At execution: caller's IPL (IPL$_ASTDEL) 

This routine calls EXE$WRITECHK and MMG$IOLOCK. 
MMG$IOLOCK locks pages in memory. If EXE$WRITELOCK 
fails because a page fault occurs during the locking procedure, 
it transfers control to the Queue-I/O-Request system service, 
which repeats the I/O request. It exits to EXE$ABORTIO if 
it cannot complete successfully. If the routine does complete 
without error, it returns control to its caller. 


Output 


Registers 

RO 

R1 

Contents 

SS$_NORMAL 

Address of the PTE that maps the first 
page of the buffer 

R2 

R3 

Destroyed 

Address of the IRP 
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Fields 


Contents 


IRP$I_SVAPTE 

IRP$W_BCNT 

IRP$V_FUNC (in 
IRP$W_STS) 


Address of the PTE that maps the first 
page of the buffer 

Size of the transfer in bytes 
A value of 0 (indicating a write function) 


IPL At exit: caller's IPL 
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EXE$WRITELOCKR 

Module: SYSQIOFDT 

This routine determines whether the process has read access to 
the requested buffer pages, and, if access is permitted, it locks 
those pages into memory. EXE$WRITELOCKR performs the 
same functions as EXE$MODIFYLOCKR, with the following 
exceptions: 

• R2, on output, contains a zero to indicate a write function. 

• IRP$M_FUNC (in IRP$W_FUNC) is clear (zero) to indicate 
a write function. 
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EXE$WRTMAILBOX 

Module: MBDRIVER 

Driver fork processes call this routine to send messages to 
mailboxes. 


Input 

Registers 

R3 

R4 

R5 

Fields 

Mailbox UCB fields 


Contents 

Size of message 
Message address 
Address of mailbox UCB 

Contents 


IPL At execution: caller's IPL (must be at or below IPL$_ 
MAILBOX) 


This routine can fail for one of the following reasons: 

• The message is too large for the mailbox. 

• The message mailbox is full of messages. 

• The system is unable to allocate memory for the message. 

• The caller lacks privilege to write to the mailbox. 


If any of the above conditions occur, EXE$WRTMAILBOX 
returns an error status to its caller. 


Output 

Registers Contents 

RO SS$_NORMAL (success) 

SS$_MBTOOSML (message too large 
for mailbox) SS$_MBFULL (mailbox full 
of messages) SS$_INSFMEM (memory 
allocation problem) SS$_NOPRIV (no 
owner write access) 

R1 - R2 Destroyed 
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EXE$ZEROPARM 

Module: SYSQIOFDT 

Device-independent FDT routine that clears the parameter field 
of the IRP and calls EXE$QIODRVPKT. 


Input 


Registers 

R3 

Contents 

Address of the l/O-request packet for the 
current I/O request 

R4 

Address of the process-control block of 
the current process 

R5 

Address of the unit-control block of the 
device assigned to the user-specified 
process I/O channel 

R6 

Address of the channel-control block that 
describes the user-specified process I/O 
channel 

R7 

Bit number of the user-specified l/O- 
function code 

R8 

AP 

Address of FDT entry 

Address of the first function-dependent 
parameter specified in the user's request 

Fields 

Contents 


IPL At execution: caller's IPL 

This routine exits by transferring control to EXE$QIODRVPKT. 


Output 


Registers 

Contents 

Fields 

IRP$I_MEDIA 

Contents 

0 


IPL At exit: caller's IPL 

For additional information, refer to Chapter 8. 
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IOC$ALOUBAMAP(IM) 

Module: IOSUBNPAG 

This routine searches the mapping register bit-map in the 
adapter-control block to allocate a contiguous set of mapping 
registers to a driver fork process. 


Input 

Registers 

R3 

R5 

Fields 

UCB$W_BCNT 

UCB$W_BOFF 

UCB$I_CRB 

CRB$I_INTD+ 

VEC$I_ADP 

VEC$V_MAPLOCK 

(in CRB$I_INTD 

+VEC$W_MAPREG) 

ADP$W_MRBITMAP 


Contents 

Number of mapping registers to allocate 
(if entry is IOCSALOUBAMAPN) 

Address of the UCB 

Contents 

Transfer byte count (if entry is 
IOC$ALOUBAMAP) 

Byte offset in page (if entry is 
IOC$ALOUBAMAP) 

Address of the CRB 

Address of the device's adapter-control 
block 

Bit that indicates whether mapping 
registers are permanently allocated to this 
controller 

Determines which mapping registers are 
available 


IPL At execution: caller's IPL 


If mapping registers are already permanently allocated to the 
controller, this routine exits successfully without allocating any 
mapping registers. Otherwise, the routine searches the mapping 
register bit-map for the required number of contiguous mapping 
registers, calls IOC$ALTUBAMAP, and exits by issuing an RSB 
instruction. 
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Output 


Registers 

RO 

Contents 

1 (success) or 0 (insufficient contiguous 
mapping registers) 

R1 - R2 

Fields 

CRB$I_INTD+ 

VEC$B_NUMREG 

CRB$I_INTD+ 

VEC$W_MAPREG 

ADP$W_MRBITMAP 

Destroyed 

Contents 

Number of mapping registers allocated 

Starting mapping register number 

Bits for allocated mapping registers set to 
zero. 


IPL At exit: caller's IPL 
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IOC$APPLYECC 

Module: IOSUBRAMS 

Disk drivers call this routine to apply an ECC correction to data 
transferred from a device into memory. This routine corrects 
the data by exclusive ORing a correction pattern from the unit- 
control block. It also sets a UCB bit to indicate that an ECC 
correction has been made. 


Input 

Registers 

RO 


R5 

Fields 

UCB$W_BCNT 
UCB$W_EC1 
UCB$W_EC2 
UCB$I_SVPN 

UCB$I_SVAPTE 


Contents 

Number of bytes of data that have been 
transferred, not including the block to be 
corrected; this must be a multiple of 512 
bytes 

Address of the unit-control block 

Contents 

Length of transfer in bytes 
Starting bit number of the error burst 
Exclusive OR correction pattern 

Address of the system-page-table entry 
of a page that is available for use by 
driver 

System virtual address of the page-table 
entry that maps the transfer 


IPL At execution: caller's IPL 


Output 

Registers Contents 

RO - R2 Destroyed 

Fields Contents 

UCB$V_ECC (in Set to 1 to show that an ECC correction 

UCB$W_DEVSTS) was made 

IPL At exit: caller's IPL 
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IOC$CANCELIO 

Module: IOSUBNPAG 

Device-independent cancel I/O routine that sets a cancel I/O 
bit in the unit-control block if the I/O-request packet being 
currently processed on the device originates from the current 
process on the specified channel and the unit is busy. 


Input 

Registers 

R2 

R3 

R4 

R5 

Fields 
IRP$I_PID 

IRP$W_CHAN 
PCB$I_PID 

UCB$V_BSY 


Contents 

Channel index number 
Address of the l/O-request packet 
Address of the current PCB 
Address of the unit-control block 

Contents 

Process identification of the process that 
queued the I/O request 

Channel index number 

Process identification of the process that 
requested cancellation 

Device busy flag (in UCB$I_STS) 


IPL At execution: caller's IPL 


Output 

Registers Contents 


Fields Contents 

UCB$V_CANCEL (in Set if I/O request should be cancelled 

UCB$I_STS) 

IPL At exit: caller's IPL 
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IOC$DIAGBUFILL 

Module: IOSUBNPAG 

Driver fork processes call this routine to fill a diagnostic 
buffer, if the QIO specifies such a buffer. This routine writes 
completion time and final error counters into buffer. It also calls 
the driver register dump routine to fill the remainder of buffer. 


Input 

Registers 

R4 

R5 

Fields 
UCB$I_IRP 

IRP$V_DIAGBUF (in 
IRP$W_STS) 

IRP$I_DIAGBUF 

UCB$B_ERTCNT 

UCB$I_DDB 

DDB$I_DDT 

DDT$I_REGDUMP 

EXE$GQ_SYSTIME 

DDT$I_REGDUMP 


Contents 

Address of the device's control/status 
register 

Address of the unit-control block 

Contents 

Address of the current IRP 

Determines whether diagnostic buffer is 
present. If set, one exists. 

Address of the diagnostic buffer, if one is 
present 

Final error retry count 

Address of the device-data block 

Address of the driver-dispatch table 

Address of the driver register dump 
routine 

Current system time (time at I/O request 
completion) 

Address of the driver register dump 
routine 


IPL At execution: caller's IPL 


This routine saves the system time and final error count in the 
diagnostic buffer. It then calls the driver register dump routine, 
and exits with an RSB instruction. 
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Output 


Registers 

RO - R1 

R2 

R3 

R4 

R5 

Fields 

Contents 

Destroyed 

Address of the DDT 

Address of the l/O-request packet 

Device CSR register 

Address of the unit-control block 

Contents 

IPL At exit: 

caller's IPL 
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IOC$INITIATE 

Module: IOSUBNPAG 


Starts a driver fork process to process an I/O-request packet. 
This routine writes the address of the I/O-request packet and 
I/O-request packet's transfer parameters into the unit-control 
block. It also clears device status bits. If the QIO specifies 
a diagnostic buffer, this routine writes system time into the 
buffer. It also executes a JMP instruction to transfer control to 
the driver start-I/O routine. 


Input 

Registers 

R3 

R5 

Fields 

IRP$I_SVAPTE 

IRP$W_BOFF 

IRP$W_SIZE 

IRP$V_DIAGBUF (in 
IRP$W_STS) 

IRP$I_DIAGBUF 

EXE$GQ_SYSTIME 

UCB$I_DDB 

UCB$I_DDT 

DDT$I_START 


Contents 

Address of the I/O-request packet 
Address of the unit-control block 

Contents 

Address of system buffer (buffered I/O) 
or address of PTE that maps process 
buffer (direct I/O). 

Byte offset of start of buffer 
Size in bytes of transfer 

Determines whether a diagnostic buffer is 
present. This field is set if one exists. 

Address of the diagnostic buffer, if one is 
present 

Current system time (when I/O 
processing began) 

Address of DDB 
Address of DDT 
Address of driver start-I/O 


IPL At execution: caller's IPL 


IOC$INITIATE exits by jumping to the driver start entry 
specified in the driver-dispatch table. 
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Output 

Contents 
Destroyed 
Contents 

Address of the start of the I/O request 
packet 

IRP$I_SVAPTE 

IRP$W_BOFF 
IRP$W_BCNT 
0 


Current system time (first quadword) 

IPL At exit: caller's IPL 



Registers 
RO - R1 
Fields 
UCB$I_IRP 

UCB$I_SVAPTE 

UCB$W_BOFF 

UCB$W_BCNT 

UCB$V_CANCEL (in 
UCB$I_STS) 

UCB$V_TIMOUT (in 
UCB$I_STS) 

diagnostic buffer 


C—65 



Operating System Routines 
IOC$IOPOST 


IOC$IOPOST 


Module: IOCIOPOST 


An interrupt-servicing routine that processes I/O-request 
packets in an I/O postprocessing queue. This routine gains 
control when the processor grants a software interrupt at 
IPL$_IOPOST. For each queue entry, it adjusts quota use 
and unlocks pages or deallocates write buffers. It queues a 
kernel-mode AST to copy final I/O status to the IOSB, to copy 
buffered read data, and to deallocate read buffers. The kernel- 
mode-AST routine queues a user mode AST if specified in the 
QIO. When the postprocessing queue is empty, IOC$IOPOST 
dismisses the interrupt. 


Input 

Registers 


Contents 


Fields 

IOC$GI_PSFL 


Contents 


Head of the I/O postprocessing queue. 
This routine uses this field to locate fields 
in the IRP. 

Process identification of the process that 
initiated the I/O request. This routine 
uses this field to locate the PCB. 


IRP$I_PID 


IPL At execution: IPL$_IOPOST, IPL$_ASTDEL 

IOC$IOPOST generates different results for direct and buffered 
I/O. For direct I/O, the routine unlocks the pages locked for 
the I/O request and sets the Queue-I/O event flag. The pages 
unlocked include any pages defined in the IRP extension area 
descriptors (if an IRPE exists). For buffered-I/O-read functions, 
the routine copies the data from the system buffer to the 
process buffer, then releases the system buffer. It also sets a 
Queue-I/O event flag, if one was requested. 

For both direct and buffered I/O, IOC$IOPOST performs the 
following functions: 

• Copies the diagnostic buffer from system to process space 
and releases the system buffer 

• Copies I/O completion status (if requested) from the I/O- 
request packet to the process's I/O-status block 
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• Queues an AST to the process, if one was requested 

• Deallocates the IRP and any IRP extensions 

Note that kernel-mode ASTs handle much of the processing 
described above. 
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IOC$LOADUBAMAP(A) 

Module: LOADMREG 

Driver fork processes for DMA transfers call this routine to load 
the UNIBUS mapping registers required by the current transfer 
with a page-frame number, the data-path number, possibly the 
byte-offset bit, and possibly the longword-access-enable bit. 
This routine confirms that enough mapping registers have been 
allocated and sets the last mapping register invalid to stop a 
wild transfer. 

Input 

Registers Contents 

R5 Address of unit-control block 


The data path and mapping registers are already allocated. 


Input 

Fields 

UCB$W_BOFF 


UCB$W_BCNT 
UCB$I_CRB 


CRB$I_INTD+ 

VEC$B_DAT APATH 

VEC$V_LWAE 

(in CRB$I_ 

INTD+VEC$B_ 

DATAPATH) 

CRB$I_ 

INTD+VEC$I_ 

NUMREG 

CRB$L_ 

INTD+VEC$I_ADP 

UBA$I_MAP 


UCB$I_SVAPTE 


Contents 

Offset to the first byte in the first page of 
the transfer 

Number of bytes in the transfer 

Address of the controller's channel- 
request block 

Number of the data path to be allocated 

Determines length of buffering. Set if 
longword buffering used (instead of 
quadword buffering) 

Number of mapping registers allocated 


Address of the adapter-control block 

Address of the first UNIBUS mapping 
register 

Address of the page-table entry for the 
first page of the transfer 
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Output 


Registers 

RO - R2 

Fields 

Contents 

Destroyed 

Contents 

Allocated mapping 
registers 

Byte offset is set for entry 
IOC$LOADUBAMAP (never set for 
IOC$LOADUBAMAPA) 


IPL At exit: caller's IPL 
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IOC$MOVFRUSER 

Module: BUFFERCTL 

This routine moves a string from a user's buffer to a driver's 
buffer in system space. 


Input 


Registers 

R1 

R2 

R5 

Fields 


Contents 

Address of the driver's buffer 
The number of bytes to move 
Address of the UCB 

Contents 


IPL At execution: caller's IPL (must be called at fork IPL) 

Output 

The string is moved to the driver's buffer. 

Registers Contents 

Fields Contents 


IPL At exit: caller's IPL (fork IPL) 
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IOC$MOVFRUSER2 

Module: BUFFERCTL 

This routine moves a string from a user's buffer to a driver's 
buffer in system space. 

This routine is useful for moving blocks of data in several 
pieces, each piece beginning within a page rather than on a 
page boundary. To begin, the driver calls IOC$MOVFRUSER. 
For each subsequent piece, the driver calls this routine. 


Input 

Registers 

RO 

R1 

R2 

R5 

Fields 


Contents 

The address of the first byte of the string 
to be moved 

Address of the driver's buffer 
The number of bytes to move 
Address of the UCB 

Contents 


IPL At execution: caller's IPL (must be called at fork IPL) 

Output 

The string is moved to the driver's buffer. 

Registers Contents 

Fields Contents 


IPL At exit: caller's IPL (fork IPL) 
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IOC$MOVTOUSER 

Module: BUFFERCTL 

This routine moves a string from a drivers's buffer in system 
space to a user's buffer. The driver must request a buffer page 
in the DPT before calling this routine. 


Input 


Registers 

R1 

R2 

R5 

Fields 

Contents 

Address of the driver's buffer 

The number of bytes to move 

Address of the UCB 

Contents 


IPL At execution: caller's IPL (must be called at fork IPL) 

Output 

The string is moved to the user's buffer. 


Registers 

Contents 

Fields 

Contents 


IPL At exit: caller's IPL (fork IPL) 
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IOC$MOVTOUSER2 

Module: BUFFERCTL 


This routine moves a string from a drivers's buffer in system 
space to a user's buffer. The driver must request a buffer page 
in the DPT before calling this routine. 

This routine is useful when moving blocks of data in several 
pieces, each piece beginning within a page rather than on a 
page boundary. To begin, the driver calls IOC$MOVTOUSER. 
For each subsequent piece, the driver calls this routine. 


Input 

Registers 


Contents 

Address of the driver's buffer 
The number of bytes to move 
Address of the UCB 

Contents 


R1 

R2 

R5 


Fields 


IPL At execution: caller's IPL (must be called at fork IPL) 

Output 

The string is moved to the user's buffer. 


Registers 


Contents 


Fields 


Contents 


IPL At exit: caller's IPL (fork IPL) 
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IOC$PURGDATAP 

Module: LIOSUB 


Device drivers call this subroutine after a data transfer. 
IOC$PURGDATAP purges the UNIBUS adapter buffered 
data path as well as checking for, logging, and clearing errors 
that occurred during the transfer. 

All device drivers that support DMA transfers must call this 
routine, including drivers of devices on processors that have no 
data paths (VAX-11/725, VAX-11/730, and Micro VAX I.) 


Input 

Registers 

R5 

Fields 


Contents 

Address of the UCB 

Contents 



IPL At execution: caller's IPL 

This routine obtains the start of UNIBUS adapter register space 
using the following chain of pointers: 

UCB$L_CRB --> CRB$L_INTD+VEC$L_ADP --> ADP$L_CSR 

This routine extracts the caller's data path number (buffered or 
direct) from the channel-request block. The routine then purges 
the data path and stores the contents of the data path register 
in Rl. IOC$PURGDATAP clears any purge errors in the data 
path register. It also sets the appropriate status in RO, computes 
the base of UNIBUS mapping registers, and writes the base into 
R2. 

A purge of data path 0 is legal and always results in success 
status. 

IOC$PURGDATAP alters RO through R3 but preserves all other 
registers. 
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Output 


Registers 

RO 

Contents 

Low bit set (success) Low bit clear 
(failure) 

R1 

Contents of data path after purge (for 
register dump routine) 

R2 

Address of the start of UNIBUS mapping 
registers (for the register-dumping routine) 

R3 

Fields 

Address of the CRB 

Contents 


IPL At exit: caller's IPL 
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IOC$RELCHAN 

Module: IOSUBNPAG 

Driver fork processes call this routine to release controller 
data channels assigned to a device. If the channel wait queue 
contains waiting fork processes, this routine dequeues a process, 
assigns the channel to that process, restores R3 through R5, and 
reactivates the suspended process. 


Input 

Registers 

R5 

Fields 

UCB$I_CRB 

CRB$I_LINK 

CRB$V_BSY (in 
CRB$B_MASK) 

CRB$I_ 

INTD+VEC$I_IDB 

IDB$I_OWNER 

CRB$I_WQFL 


Contents 

Address of the unit-control block 

Contents 

Address of the channel-request block 
Address of the secondary CRB 
Set if the channel is busy 

Address of the interrupt-data block 

Channel's owner UCB address 
Head of the queue of waiting UCBs 


IPL At execution: caller's IPL 


Output 

Registers 

RO - R2 

Fields 

IDB$I_OWNER 

CRB$V_BSY 


Contents 

Destroyed 

Contents 

Clear (if no driver is 
channel) 

Clear (if no driver is 
channel) 


waiting for the 
waiting for the 


IPL At exit: caller's IPL 
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IOC$RELDATAP 

Module: IOSUBNPAG 


Driver fork processes call this routine to release a UNIBUS 
adapter buffered data path. This routine performs no operation 
if a data path is permanently allocated to the controller. If 
the data path wait queue contains waiting fork processes, it 
dequeues a process, allocates the data path to that process, 
restores R3 through R5, and reactivates the suspended process. 
This routine should not be called unless the driver owns a 
buffered data path. 


Input 


Registers 

R5 

Fields 


UCB$I_CRB 

CRB$I_ 

INTD+VEC$I_ADP 


CRB$I_INTD+ 

VEC$B_D AT AP ATH 


VEC$V_PATHLOCK 


ADP$I_DPQFL 


Contents 

Address of unit-control block 

Contents 

Address of the channel-request block 
Address of the adapter-control block 

Data path specifier 

Set to 1 to indicate that the data path is 
permanently allocated to the controller 

Head of the adapter data path wait queue 


IPL At execution: caller's IPL 


If the bit-map is corrupted, this routine signals a bugcheck with 
message code INCONSTATE. After IOC$RELDATAP completes 
successfully, it exits with an RSB instruction. 


Contents 

Destroyed 



Output 

Registers 

RO - R2 
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Fields 

ADP$W_DPBITMAP 

Contents 

Data path is set to free if not allocated to 
another driver fork process 

Bits 0 through 

4 (in CRB$L_ 
INTD+VEC$B_ 
DATAPATH) 

Clear 

IPL At exit: caller's IPL 
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IOC$RELMAPREG 

Module: IOSUBNPAG 

Driver fork processes call this routine to release a set of 
UNIBUS adapter mapping registers. This routine performs 
no operation if mapping registers are permanently allocated 
to the controller. If the mapping-register-wait queue contains 
waiting fork processes, it dequeues a process and attempts to 
allocate the required set of mapping registers. If successful, it 
restores R3 through R5 and reactivates the suspended process. 

If not successful, it reinserts the fork process in the mapping- 
register-wait queue and dequeues the next process. This routine 
assumes that the caller is the current owner of the controller 
data channel. 


Input 

Registers 

R5 

Fields 

UCB$I_CRB 

VEC$V_MAPLOCK 

(in CRB$I_INTD+ 

VEC$W_MAPREG) 

CRB$I_ 

INTD+VECSl_ADP 

CRB$I_INTD+ 

VEC$W_MAPREG 

CRB$I_INTD+ 

VEC$B_NUMREG 

ADP$I_MRQFL 


Contents 

Address of unit-control block 

Contents 

Address of the CRB 

If set, indicates that mapping registers are 
permanently allocated to the controller 

Address of the adapter-control block 

Number of the starting mapping register 

Number of mapping registers to release 

Head of the queue of waiting drivers 


IPL At execution: caller's IPL 


IOC$RELMAPREG calls IOC$ALTUBAMAP and 
IOC$ALOUBAMAP. It exits with an RSB instruction. 
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Output 


Registers 

R0 - R2 

Contents 

Destroyed 

Fields 

Contents 

ADP$W_MRBITMAP 

Mapping registers set to free 

IPL At exit: caller's IPL 
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IOC$RELSCHAN 

Module: IOSUBNPAG 

This routine releases a secondary controller's data channel, 
the MASSBUS adapter's controller data channel. For more 
information, refer to Appendix F. 

This routine has the same inputs and outputs as 
IOC$RELCHAN. 
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IOC$REQCOM 

Module: IOSUBNPAG 

Driver fork processes call this routine after a device I/O 
operation and all device-dependent processing of an I/O 
request are complete. This routine writes RO and R1 into 
the I/O-request packet's status field. It then inserts the I/O- 
request packet into the I/O postprocessing queue. If error 
logging is occurring, it writes final status into the error message 
buffer and calls ERL$RELEASEMB. If the pending-I/O queue 
contains entries, it dequeues an I/O-request packet and calls 
IOC$INITIATE. Otherwise, it clears a unit-control-block-busy 
bit to indicate that the device is idle. 


Input 

Registers 

RO 

R1 

R5 

Fields 

UCB$V_ERLOGIP (in 
UCB$I_STS) 

UCB$I_STS 

UCB$B_ERTCNT 

UCB$I_EMB 

UCB$I_IRP 


Contents 

First longword of I/O status 
Second longword of I/O status 
Address of unit-control block 

Contents 

Set or clear. Determines whether error 
logging should be performed 

Final device status 
Final error counters 

Address of the error log message buffer 
Address of the IRP 


IPL At execution: caller's IPL 


This routine places the I/O-request packet in the queue headed 
by IOC$GL_PSBL. If UCB$L_IOQEL has a packet queued to 
it, IOC$REQCOM sends the packet to IOC$INITIATE. This 
routine exits by branching to IOC$RELCHAN. 

Output 

Registers Contents 

R2 - R3 Destroyed 

If IOCSINITIATE is called, other registers will be destroyed. 
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Fields 

IRP$I_MEDIA 

IRP$I_MEDIA+4 

EMB$Q_IOSB 

UCB$I_OPCNT 

EMB$B_ERTCNT 

EMB$B_ERTCNT+1 

EMB$W_DV_STS 

UCB$V_BSY 

IPL At exit: caller's IPL 


Contents 

I/O status (RO) 

I/O status (R1) 

I/O status (RO and R1) 

Incremented by 1 

UCB$B_ERTCNT 

UCB$B_ERRCNT 

UCB$W_STS 

Clear 
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IOC$REQDAT AP(NW) 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a UNIBUS 
adapter buffered data path for a DMA transfer. This routine 
performs no operation if a data path is permanently allocated to 
the controller. This routine locates a free data path and writes 
the data path number in the CRB. If no data paths are free, it 
saves R3 and R4 in the UCB fork block, inserts the fork block 
address in a data path wait queue, and suspends the driver fork 
process. 


Input 

Registers 

R5 

O(SP) 

4(SP) 

Fields 

UCB$I_CRB 

VEC$V_PATHLOCK 

(in CRB$I_INTD+ 

VEC$B_DAT APATH) 

CRB$I_ 

INTD+VECSl_ADP 

ADP$W_DPBITMAP 


Contents 

Address of unit-control block 

Caller's return address 

Return address of the caller's caller 

Contents 

Address of the channel-request block 

If set, indicates that the data path already 
is allocated 

Address of the adapter-control block 
Indicates what data paths are available 


IPL At execution: caller's IPL 


If IOC$REQDATAP cannot allocate a data path, and NW is 
not specified, the routine saves process context by placing the 
contents of R3, R4 and the PC in the UCB fork block and 
placing R5 in the data path wait queue (ADP$L_DPQBL). If, 
however, NW is specified, the routine does not suspend the 
process to wait for the data path. 
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Output 

Registers 

RO 

Fields 

CRB$L_INTD+ 
VEC$B_DAT APATH 

ADP$W_DPBITMAP 


Contents 

SS$_NORMAL (success) 0 (failure) 

Contents 

Data path number 

Bit for allocated data path clear 


IPL At exit: caller's IPL 
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IOC$REQMAPREG 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a set of 
UNIBUS adapter mapping registers for a DMA transfer. 

This routine performs no operation if mapping registers are 
permanently allocated to the controller. 

This routine locates the required number of mapping registers 
and writes the number of registers and the number of the first 
register into the CRB. If sufficient mapping registers are not 
available, it saves R3 and R4 in the UCB fork block, inserts 
the fork block's address in a mapping-register-wait queue, and 
suspends the driver fork process. 


Input 

Registers 

R5 

O(SP) 

4(SP) 

Fields 

UCB$W_BCNT 
UCB$W_BOFF 
UCB$I_CRB 

CRB$I_INTD+ 

VEC$I_ADP 

VEC$V_MAPLOCK 
(in CRB$L_ 
INTD+VEC$W_ 
MAPREG) 

ADP$W_MRBITMAP 


Contents 

Address of unit-control block 

Return address of caller 

Return address of the caller's caller 

Contents 

Transfer byte count 

Byte offset into page of start of buffer 

Address of CRB 

Address of the adapter-control block 
Determines status of map-lock bit 


Adapter's mapping-register-allocation 
bit-map 


IPL At execution: caller's IPL 


If registers are not available, this routine suspends the process 
by saving the following context: 

• R3 and R4 are saved in UCB$L_FR3 and UCB$L_FR4, 
respectively. 

• PC is saved in UCB$L_FPC. 
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• R5 is saved in ADP$L_MRQBL, which is the adapter's 
mapping-register-wait queue. 


Output 


Registers 

RO 

R1 - R2 

Fields 

CRB$I_INTD+ 

VEC$W_MAPREG 

CRB$I_INTD+ 

VEC$B_NUMREG 

ADP$W_MRBITMAP 

Contents 

SS$_NORMAL (success) 

Destroyed 

Contents 

The number of the first mapping register 
allocated 

Number of mapping registers allocated 

Allocated mapping registers 


IPL After execution: caller's IPL 
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IOC$REQPCHAIMH 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a channel 
on the primary controller with high priority. If the controller 
data channel is idle, this routine writes the UCB address in 
the interrupt-data block and returns the CSR address in R4. 
Otherwise, it saves R3 in the UCB fork block, inserts the fork 
block address at the front of the channel wait queue, and 
suspends the driver fork process. 


Input 

Registers 

R5 

O(SP) 

4(SP) 

Fields 

UCB$I_CRB 

CRB$I_LINK 

CRB$I_ 

INTD+VEC$I_IDB 

CRB$V_BSY in 
CRB$B_MASK 

IDB$I_CSR 


Contents 

Address of unit-control block 
Return address of the caller 
Return address of the caller's caller 

Contents 

Address of the channel-request block 

Address of the secondary channel-request 
block 

Interrupt-data block address 

Set or clear. If set, indicates that the 
channel is busy 

Address of device CSR 


IPL At execution: caller's IPL 


If the channel is busy, this routine saves driver context by 
storing the contents of R3 and R4 in UCB$L_FR3 and 
UCB$L_FR4, respectively, storing 0(SP) in UCB$L_FPC and 
placing the contents of R5 in the CRB wait queue (CRB$W_ 
WQFL). 

IOC$REQPCHANH exits by issuing an RSB instruction. 
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Output 


Registers 

RO - R2 

R4 

Fields 

IDB$!_OWNER 

Contents 

Destroyed 

IDB$I_CSR 

Contents 

R5 


IPL At exit: caller's IPL 
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IOC$REQPCHANL 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a channel on 
the primary controller with low priority. This routine performs 
in the same manner as IOC$REQPCHANH, except that, should 
driver have to wait for the channel, IOC$REQPCHANL places 
the UCB at the end of the channel wait queue. 


C—90 






Operating System Routines 

IOC$REQSCHANH 


IOC$REQSCHANH 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a channel on 
the secondary controller with high priority. 

The input to and output from this routine are the same as for 
IOC$REQPCHANH, except that the secondary controller data 
channel is assigned. 
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IOC$REQSCHANL 

Module: IOSUBNPAG 

Driver fork processes call this routine to request a channel on 
the secondary controller with low priority. 

The input to and output from this routine are the same as for 
IOC$REQPCHANH, except that the secondary controller data 
channel is assigned. 
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IOC$RETURN 

Module: IOSUBNPAG 

This routine merely returns by issuing an RSB instruction. It 
has no input requirements and produces no output. 
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IOC$VERIFYCHAN 

Module: IOSUBPAGD 

Drivers call this routine to validate a user-supplied channel 
number, contruct a channel index, and obtain the address of the 
channel-control block to which the channel number points. 


Input 


Registers 

RO 

Fields 

Contents 

Channel number 

Contents 


CTLSGI—CCBASE Base address of the process channel- 

control-block table 

IPL At execution: IPL$_ASTDEL or below 

Because this routine gains access to information stored in user 
process virtual address space, it should only be called when the 
user process is mapped. 


Output 


Registers 

RO 

Contents 

SSS—NORMAL (success) SS$_IVCHAN 
(invalid channel number) SS$_NOPRIV (no 
privilege to access specified channel) 

R1 

R2 

Fields 

Address of channel-control block 

Channel index number 

Contents 

IPL At exit: 

caller's IPL 
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IOC$WFIKPCH 


Module: IOSUBNPAG 


Driver fork processes call this routine to suspend driver 
processing to wait for an interrupt or device timeout and still 
retain the controller data channel. This routine saves R3, R4, 
and the driver's return PC from top of stack in the UCB fork 
block. It sets UCB bits to indicate that an interrupt or a timeout 
is expected and sets the timeout time in the unit-control block. 
It clears the UCB bit that indicates that the unit is timed out 
and lowers IPL back to the IPL saved on top of stack. Then, it 
returns to the caller of the driver fork process. 

The two bytes following the JSB to IOC$WFIKPCH contain the 
relative offset to the timeout routine. 


Input 

Registers 

R5 

O(SP) 


Contents 

Address of unit-control block 

Address following the JSB to 
IOC$WFIKPCH 

Timeout value in seconds 

IPL to which to lower before returning to 
the caller's caller 

Return address of the caller's caller 

Contents 

Absolute time. Used to compute time at 
which device times out 


4(SP) 

8(SP) 


12(SP) 

Fields 

EXESGI_ABSTIM 


IPL At execution: Fork a device IPL (caller's IPL) 

This routine removes 0(SP) through 11 (SP) from the stack 
explicitly and 12(SP) through 15(SP) implicitly by exiting with 
an RSB instruction, which returns to the caller's caller. 
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Output 


Registers 

Contents 

Fields 

UCB$I_DUETIM 

Contents 

Sum of timeout value and EXE$GI_ 

ABSTIM 

UCB$V_INT 

Set to indicate that interrupts are 
expected on the device 

UCB$V_TIM 

Set to indicate that timeouts are expected 
on the device 

UCB$V_TIMOUT 

Cleared to indicate that unit is not timed 
out 

UCB$I_FR3 

UCB$I_FR4 

UCB$FPC 

R3 

R4 

0(SP)+2 


IPL At exit: IPL specified in 8(SP) 
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IOC$WFIRLCH 

Module: IOSUBNPAG 

Driver fork processes call this routine to suspend driver 
processing to wait for an interrupt or device timeout first 
releasing the controller data channel. 

The input to and output from this routine is the same 
as IOCSWFIKPCH except that IOC$WFIRLCH exits to 
IOC$RELCHAN, which releases the controller data channel. 
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Writing Device Drivers for the 
Micro VAX I Q22 Bus 


D.1 Introduction 

This appendix details the differences between MicroVAX I 
Q-bus and UNIBUS drivers. It also describes how to modify 
a UNIBUS driver to make it drive a compatible device on the 
MicroVAX I Q22 bus. 

To use this appendix effectively, you should have available 
for reference the MicroVAX I Owner's Manual (order number 
EK-KD32A-UG-001), the MicroVAX I CPU Technical Description 
(order number EK-KD32A-TD-001), the MicroVAX Handbook 
(1984), and the Microcomputer Interface Handbook. 

The MicroVAX I Q22 bus is very similar to the UNIBUS. Non- 
DMA transfers can be performed for a device on the MicroVAX 
I Q22 bus by the same, unaltered driver that performs them 
for the equivalent device on the UNIBUS. Some differences 
exist between the busses, however, and these differences are 
of interest if you want to support a device on which DMA 
transfers are to be done. 

In order for the same DMA device driver to function for 
equivalent UNIBUS and MicroVAX I Q-bus drivers, the driver 
must contain some run-time-conditional code. Appendix E 
contains an examble of an RL 02 driver that support the RL11 
on the UNIBUS and the RLV11 on the MicroVAX I Q-bus. 
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Figure D-1 UNIBUS Configuration 



ZK-1794-84 


D.2 A Comparison of the UNIBUS and the MicroVAX I Q22 
Bus 


The following lists show the differences and similarities 
between the MicroVAX I Q22 bus implementation and the 
UNIBUS. 
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The characteristics of the UNIBUS system are listed below. 

• The UNIBUS uses 18-bit addresses. 

• The UNIBUS has an 8Kb I/O page. 

• The UNIBUS is connected to the CPU's backplane by means 
of the UNIBUS adapter (UBA). 

• The UNIBUS adapter contains 496 mapping registers, 
which are used to to map UNIBUS physical addresses to 
VAX/VMS virtual addresses. 

• The UNIBUS adapter provides buffered data paths, which 
optimize CPU-to-UNIBUS data transfers. 

• The UNIBUS adapter has a byte-offset register, thus words 
that are not word-aligned can be transferred to and from 
any device on the UNIBUS regardless of whether the device 
supports non-word-aligned transfers. 

• The UNIBUS is one of the I/O buses available on a VAX- 
11/780, a VAX-11/750, and the VAX-11/730 family of 
processors. In addition, each system has its own particular 
CPU backplane. 

• On the VAX-11/780 family of processors, the UNIBUS uses 
indirect-vector interrupt dispatching. On a VAX-11/750 
and the VAX-11/730 family of processors, the UNIBUS 
uses direct-vector interrupt dispatching. In each case, the 
vector addresses can range from 0 to 777 8 . 

• The UNIBUS provides four device IPLs (BR4-BR7) on which 
device priority is based. These device IPLs are independent 
of the position of the devices on the UNIBUS. 


The characteristics of the MicroVAX I Q22 bus are listed below. 

• The MicroVAX I Q22 bus uses 22-bit addresses. It supports 
only those DMA controllers that are capable of 22-bit 
addressing. 

• Both the UNIBUS and the Q22 bus have an 8Kb I/O page. 

• The MicroVAX I Q22 bus connects memory to the 
MicroVAX I CPU and to each peripheral device, hence 
no adapter is required. 
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Figure D—2 MicroVAX I Configuration 



ZK-1793-84 


• The MicroVAX I Q22 bus has no mapping registers, so 
no mapping of physical bus addresses to virtual memory 
addresses is possible. Thus data transferred to or from 
contiguous bus addresses must be transferred from or to 
contiguous physical addresses in MicroVAX I memory. 

Note, however, that some controllers that can do DMA 
transfers on the MicroVAX I Q22 bus have microcode 
that allows the controller to do physical-to-virtual address 
mapping. This allows such controllers to do scatter-gather 
mapping, eliminating the need for transfers to be made to 
or from physically contiguous main memory. The RD/RX 
controller, which MicroVAX I uses for its system disk, uses 
such a controller. 

• The MicroVAX I Q22 bus has no buffered data paths. 

• The MicroVAX I Q22 bus has no byte-offset register, so, on 
devices that are only capable of word-aligned transfers, only 
word-aligned transfers are possible. 

• The MicroVAX I Q22 bus has an address space with 22-bit 
addresses. Furthermore, the MicroVAX I Q22 bus serves as 
both the system's I/O bus and backplane. 

• The MicroVAX I Q22 bus provides direct-vector interrupt 
dispatching, and the vector addresses can range from 0 to 
777 8 . 
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• The MicroVAX I Q22 bus provides four device IPLs (BR4- 
BR7). Devices with higher IPL must be configured closer 
to the CPU than devices with lower IPL. 

The MicroVAX architecture specifies 31 IPLs. Their uses are 
listed below. 


IPL 

Interrupt 

IF 

Unused 

IE 

Power failure 

ID 

Memory write error 

18 to 1C 

Unused 

17 

Q22 bus IRQ7 

16 

Interval timer and Q22 IRQ6 

15 

Q22 bus IRQ5 

14 

Console receive, console transmit, and Q22 bus 
IRQ4 

10 to 13 

Unused 

01 to OF 

Software interrupts 


Interrupts from devices on the Q22 bus are arbitrated by 
comparing the level of the interrupting device to the current 
processor IPL. But when an interrupt from a device is 
serviced, the IPL is raised to 17 (hex). Subsequent interrupts 
lower than the current IPL of the processor are blocked, 
including other interrupts from the device being serviced. 

Note that the interval timer interrupts at IPL 16 (hex). 
Because of this, the driver of a Q22 bus device that raises 
IPL to 16 (hex) or above must lower IPL below 16 (hex) 
within 10 milliseconds or an interval-timer interrupt will be 
lost. 


D.3 A Comparison of MicroVAX I Q22 bus and UNIBUS 
Drivers 

This comparison is divided into two parts. The first describes 
the drivers that handle non-DMA transfers. The second part 
describes the drivers that handle DMA transfers. 
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D.3.1 Non-DMA Transfers 

In non-DMA transfers, the driver reads from and writes into 
the device's registers, and in this manner moves a word of 
data to or from the device. Non-DMA devices do not use 
mapping registers, so drivers of such UNIBUS devices will drive 
equivalent devices on the MicroVAX I Q22 bus. The driver 
of a UNIBUS device needs no modification to make it drive 
the equivalent device on a MicroVAX I Q22 bus. Non-DMA 
devices do not use data paths, so the lack of data paths in the 
MicroVAX I Q22 bus has no impact on the drivers of such 
devices. 

Examples of UNIBUS devices that do non-DMA transfers are 
the LP-11 and the DZ-11. Corresponding Q22 bus devices that 
do non-DMA transfers are, respectively, the LPV-11 and the 
DZV-11. 


D.3.2 DMA Transfers 

When a UNIBUS device driver does a DMA transfer, it allocates 
mapping registers and, optionally, a data path, and sets up the 
transfer by means of the device's registers. The device then 
accesses memory directly by means of the UNIBUS, transferring 
all the data requested. When the transfer is complete, the 
device notifies the driver by requesting an interrupt. 

The device can access memory directly by means of the 
UNIBUS because the UNIBUS adapter contains mapping 
registers, which allow the device to access scattered, physical 
memory addresses as contiguous, physical UNIBUS addresses. 

Take a buffer, for example, that consists of virtual pages 400, 
401, 402, and 403, which are physical pages 1003, 204, 1190, 
and 240, respectively. For a UNIBUS device to access this 
buffer, the driver requests four mapping registers, then places 
the physical addresses of these pages in the mapping registers. 
Assume the driver has allocated four mapping registers, 127 
through 130. The driver loads them as follows: 


Mapping 

Contents 

Register 

(physical 

127 

1003 

128 

204 

129 

1190 

130 

240 
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Writing Device Drivers for the MicroVAX I Q22 Bus 


The device and the UNIBUS can transfer data into or out of 
these physical pages without intervention by the driver. The 
device requests an interrupt only when all the data in these 
four pages have been transferred. 

The MicroVAX I Q22 bus has no data paths and no mapping 
registers, so drivers of MicroVAX I Q22 bus devices must use 
a different strategy from the one UNIBUS drivers use. The 
lack of data paths does not require Q22 bus drivers to take any 
special action; the lack of mapping registers does. 

The Q22 bus device must use physical addresses to access the 
pages in the user's buffer. Because the device has no mapping 
registers, the buffer's physical pages must be contiguous. There 
is no guarantee that this is the state of the user's buffer. So 
the driver must allocate an intermediate buffer consisting 
of contiguous physical pages. The driver never deallocates 
this buffer unless the driver is being unloaded (by means of 
SYSGEN's UNLOAD command.) 

The best time to allocate such a buffer is during the device's 
initialization. Memory is most likely contiguous at that time. 
Later it will be much more difficult to obtain a buffer that is 
physically contiguous. 

To be sure that the buffer you allocate to the driver is 
contiguous, use the VAX/VMS routine EXE$ALOPHYCNTG. 
This routine, defined in module MEMORYALC, expects R1 to 
contain the number of physically contiguous pages to allocate. 
This routine must be called at IPL$_SYNCH. 

When EXE$ALOPHYCNTG returns control to its caller, RO 
contains a status code (SUCCESS, ISSFMEM, or INSFSPTS), 
and, if the allocation succeeds, R2 contains the system virtual 
address of the first allocated block. It preserves the contents of 
all other registers, and returns control to its caller at the caller's 
IPL. 

The size of the buffer must depend on the device's 
characteristics and the size of the transfers requested on the 
device. A buffer of four pages is likely to be large enough 
for most disk transfers, for example; but if you have enough 
memory on your system, you might want to make your buffer 
the size of a disk track in order to reduce disk latency. In 
any event, large transfers to the device can be segmented into 
transfers the size of your intermediate buffer. 
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When a user requests a transfer to a MicroVAX I Q22 bus 
device, the driver copies the data from the user's buffer into 
the intermediate, physically contiguous buffer by means of 
the routine IOC$MOVFRUSER. The driver must ensure that 
the buffer is word-aligned because the MicroVAX I has no 
byte-offset capability. The driver then sets up the device for 
the DMA transfer from the intermediate, physically contiguous 
buffer to the device, and starts the device. 

When a user requests a transfer from a MicroVAX I Q22 
bus device, the driver moves the data from the device to the 
intermediate, physically contiguous buffer by means of a DMA 
transfer, then calls IOC$MOVTOUSER to copy the data into 
the user's buffer. 

When a DMA transfer is completed, the driver should call 
IOC$PURGDATAP in order to detect and log any memory 
errors that might have occurred during the transfer. 
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A Sample Q-Bus Driver 




This example driver, DLDRIVER, drives devices on both the 
UNIBUS and the Q-bus. 

.TITLE DLDRIVER - VAX/VMS RL11/RL01,RL02 DISK DRIVER 
.IDENT 'V03-008' 

**************************************************************************** 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 

ALL RIGHTS RESERVED. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


**************************************************************************** 
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A Sample Q-Bus Driver 


FACILITY: 

VAX/VMS RL11/RL01,RL02 DISK DRIVER 
AUTHOR: 

C. F. Programmer 05-0CT-1979 
MODIFIED BY: 

V03-008 

V03-007 

V03-006 

V03-005 

V03-004 

V03-003 

V03-002 

V03-001 

** 

.PAGE 

; ABSTRACT: 

; THIS MODULE CONTAINS THE TABLES AND ROUTINES NECESSARY TO 

; PERFORM ALL DEVICE-DEPENDENT PROCESSING OF AN I/O REQUEST 

; FOR RLll/RLOl,RL02 DISK TYPES ON A VAX/VMS SYSTEM. 

; THE DISKS HAVE THE FOLLOWING PHYSICAL GEOMETRY: 



# CYL 

TRACKS/ 

CYLINDER 

SECTORS/ 

TRACK 

BYTES/ 

SECTOR 

MAXIMUM 

BLOCKS 

RL01 

256 

2 

40 

256 

10240 

RL02 

512 

2 

40 

256 

20480 


WHMOOOl B. M. Programmer 

Added MicroVAX I/QBUS support. 


15-May-1984 


27-Apr-1984 


RAS0300 R. S. Programmer 

Add DEV$M_NNM characteristic to DECHAR2 so that these 
devices will have the "node$" prefix. 

PRD0033 P. R. Programmer 09-Sep-1983 

Added EXE$LCLDSKVALID to function decision table. 


R0W0211 R. 0. Programmer 16-AUG-1983 

Change device-dependent UCB definition base from UCB$W_BCR+2 
to UCB$K_LCL_DISK_LENGTH. 

KDM0059 K. D. Programmer 14-Jul-1983 

Change time-wait loops to use new TIMEDWAIT macro. 

PRD0020 P. R. Programmer 26-Apr-1983 

Modified FATALERR routine to return SS$_PARITY only for 
errors that possibly indicate bad media. All other error 
conditions which formerly returned SS$_PARITY now return 
SS$_CNTLERR. 


KDM0002 
Added SDYNDEF. 


K. D. Programmer 


28-Jun-1982 


KTA0100 K. T. Programmer 

Add code to set UCB$L_MEDIA_ID. 


07-Jun-1982 
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A Sample Q-Bus Driver 



SINCE THE SECTOR SIZE IS ONLY 1/2 BLOCK, LOGICAL TO PHYSICAL 
CONVERSION OF THE DISK ADDRESS IS DONE IN THE DRIVER STARTIO 
ROUTINE RATHER THAN IN THE IOC$CVTLOGPHY FDT ROUTINE. 


OVERLAPPED SEEKS ARE NOT ATTEMPTED BECAUSE THE DEVICE DOES 
NOT INTERRUPT AT THE COMPLETION OF A SEEK. 

ALSO, THE DEVICE DOES NOT PERFORM AN IMPLICIT SEEK WHEN PERFORMING 
A READ OR WRITE FUNCTION,SO SEEK FUNCTIONS ARE ISSUED BY THIS 
DRIVER WHERE NECESSARY PRIOR TO ISSUING A READ OR WRITE FUNCTION. 
THE READ OR WRITE FUNCTION IS THEN ISSUED AS SOON AS THE RL11 
CONTROLLER COMES READY (WHILE THE SEEK IS IN PROGRESS), AND A 
WAIT-FOR-INTERRUPT (UPON COMPLETION OF THE READ OR WRITE) IS 
ISSUED. IF A SEEK FUNCTION IS REQUESTED SEPARATELY FROM A READ OR 
WRITE, A DUMMY READ HEADER FUNCTION IS ISSUED FOLLOWING THE SEEK 
FUNCTION AND A WAIT-FOR-INTERRUPT (UPON COMPLETION OF THE READ 
HEADER) IS ISSUED. 

THE IO$X_INHSEEK FUNCTION MODIFIER IS TREATED AS A NO-OP BY 
THIS DRIVER, SINCE AN EXPLICIT SEEK IS NECESSARY FOR THE RL02 
TO TRANSFER DATA PROPERLY. 



THE RL'S DO NOT READ OR WRITE BEYOND THE END OF TRACK (THEY DO NOT 
AUTOMATICALLY SEEK THE NEXT TRACK), SO ALL READ AND WRITE FUNCTIONS 
ARE BROKEN UP BY THIS DRIVER INTO PARTIAL TRANSFERS TO THE END OF 
TRACK, FOLLOWED BY A SEEK TO THE NEXT TRACK, THEN ANOTHER READ OR 
WRITE FUNCTION UNTIL THE TOTAL DATA TRANSFER IS COMPLETE. 


.PAGE 

.SBTTL EXTERNAL AND LOCAL DEFINITIONS 


EXTERNAL SYMBOLS 

SADPDEF 

SCRBDEF 

SDCDEF 

$DDBDEF 

$DEVDEF 

SDPTDEF 

$DYNDEF 

SEMBDEF 

$IDBDEF 

SIODEF 

$IRPDEF 

$PRDEF 

$PTEDEF 

SSSDEF 

SUCBDEF 

$VADEF 

$VECDEF 



DEFINE ADAPTER CONTROL BLOCK 
DEFINE CHANNEL REQUEST BLOCK 
DEFINE DEVICE CLASS 
DEFINE DEVICE DATA BLOCK 
DEFINE DEVICE CHARACTERISTICS 
DEFINE DRIVER PROLOGUE TABLE 
DEFINE DYNAMIC DATA STRUCTURE TYPES 
DEFINE ERROR MESSAGE BUFFER 
DEFINE INTERRUPT DATA BLOCK 
DEFINE I/O FUNCTION CODES 
DEFINE I/O REQUEST PACKET 
DEFINE PROCESSOR REGISTERS 
DEFINE SYSTEM PTES 
DEFINE SYSTEM STATUS CODES 
DEFINE UNIT-CONTROL BLOCK 
DEFINE VIRTUAL ADDRESS BITS 
DEFINE INTERRUPT VECTOR BLOCK 
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A Sample Q-Bus Driver 


LOCAL MACROS 


EXFUNCL 

BRANCH TO SUBROUTINE WHICH REQUESTS CHANNEL (IF NOT ALREADY OWNED), 
EXECUTES FCODE (OR R3) FUNCTION, AND BRANCHES TO BDST ON ERROR 

.MACRO EXFUNCL BDST,FCODE 
.IF NB FCODE 
MOVZBL #CD'FCODE,R3 
. ENDC 

BSBW FEXL 
.BYTE BDST-.-1 

. ENDM 
GENF 

GENERATE FUNCTION TABLE ENTRY AND CASE TABLE INDEX SYMBOL 

.MACRO GENF FCODE 

CD'FCODE=.-FTAB/2 

.WORD FCODE!RL_CS_M_IE ;FCODE WITH INT ENABLE BIT 

.ENDM 
CKPWR 

DISABLE INTERRUPTS, CHECK IF POWER HAS FAILED, 

AND PUT DEVICE UNIT NUMBER IN R2<9:8> 


IS FCODE NON-BLANK? 

IF NB, SPECIFY FCODE FUNCTION 
IF B, SPECIFY FNTN IN EXISTING R3 
EXECUTE FUNCTION 
WHERE TO GO ON ERROR 


.MACRO CKPWR ?L1 
CLRL R2 

INSV UCB$W_UNIT(R5),- 
#8,#2,R2 

DSBINT 

BBC #UCB$V_POWER,- 

UCB$W_STS(R5), 

ENBINT 

BRW RETREG 

LI: 

.ENDM 


LOCAL SYMBOLS 


RL_NUM_REGS =4 

RL.SLM =5 

UCB$B_DL_DCHEK =UCB$W_OFFSET+l 


;CLEAR R2 FOR UNIT NUMBER 
;PUT UNIT # IN R2<9:8> 

;DISABLE INTERRUPTS 
;IF CLR, NO POWER FAILURE 

;POWER FAILURE - ENABLE INTERRUPTS 
; EXIT 

;RETURN FOR NO POWER FAILURE 


NUMBER OF DEVICE REGISTERS 
STATE=SEEK LINEAR MODE (READY TO GO) 
REDEFINE FOR DATA CHECK USE 
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A Sample Q-Bus Driver 


UCB OFFSETS WHICH FOLLOW THE STANDARD UCB FIELDS 


$DEFINI UCB 


.=UCB$K_LCL_DISK_LENGTH 


$DEF 

UCB$W_DL_PBCR 

.BLKW 

1 

$DEF 

UCB$W_DL_CS 

.BLKW 

1 

$DEF 

UCB$W_DL_BA 

.BLKW 

1 

$DEF 

UCB$W_DL_DA 

.BLKW 

1 

$DEF 

UCB$W_DL_MP 

.BLKW 

1 

$DEF 

$DEF 

UCB$W_DL_DPN 

UCB$L_DL_SVAPTE 

.BLKW 

1 

$DEF 

$DEF 

UCB$L_DL_DPR 

UCB$L_DL_BUFADR 

. BLKL 

1 

$DEF 

$DEF 

UCB$L_DL_FMPR 

UCB$A_DL_MOVRTN 

. BLKL 

1 

$DEF 

UCB$L_DL_PMPR 

.BLKL 

1 

$DEF 

UCB$B_DL_DPPE 

. BLKB 

1 

$DEF 

UCB$W_DL_DB 

.BLKW 

3 

$DEF 

UCB$B_DL_XBA 

.BLKB 

1 

$DEF 

UCB$W_DL_SBA 

.BLKW 

1 

$DEF 

UCB$A_DL_BUF_VA 

.BLKL 

1 

$DEF 

UCB$A_DL_BUF_PA 

.BLKL 

1 

$DEF 

UCB$W_DL_FLAGS 
SVIELD UCB,0,<- 

.BLKW 

1 


<DL_22BIT,,M>,- 
<DL_MAPPING,, M>, - 
> 

$DEF UCB$K_DL_LEN .BLKW 1 
$EQU UCB$K_DL_BUFSZ 20 

$DEFEND UCB 


START OF UCB DEFINITIONS 

BEGIN DEFINITIONS AT END OF UCB 

PARTIAL BYTE COUNT 

CONTROL STATUS REGISTER 

BUS ADDRESS REGISTER 

DISK ADDRESS REGISTER 

MULTIPURPOSE REGISTER 

DATA-PATH NUMBER 

SAVED SVAPTE OF THE USER'S BUFFER 

DATA-PATH REGISTER 

USER BUFFER ADDRESS 

FINAL MAP REGISTER 

BUFFER MOVE ROUTINE ADDRESS 

PREVIOUS MAP REGISTER 

DATA-PATH PURGE ERROR 

DATA BUFFER REGISTER 

BUS ADDRESS EXTENSION BITS 

SAVED BUFFER ADDRESS 

PHYSICAL BUFFER VIRTUAL ADDRESS 

PHYSICAL BUFFER PHYSICAL ADDRESS 

FLAGS 

START THE FLAG DEFINITIONS 
22 BIT ADDRESSING 
ADAPTER MAPPING 
END OF FLAG DEFINITIONS 
LENGTH OF UCB 

BUFFER SIZE = 40 SECTORS * 

256 BYTES/SECTOR / 512 BYTES/PAGE 
END OF UCB DEFINITONS 


RL11/RL01 REGISTER OFFSETS FROM CSR ADDRESS 


$DEFINI RL 


START OF REGISTER DEFINITIONS 


$DEF RL_CS .BLKW 1 

_VIELD RL_CS,0,<- 
<DRDY,,M>,- 
<FCODE,3>.- 
<XBA,2>,- 
<IE,,M>,- 
<CRDY,,M>,- 
<DS,2>,- 
<OPI,,M>,- 
<CRC,,M>,- 
<DLT,,M>,- 
<NXM,,M>,- 
<DE,,M>,- 
<CE,,M>- 


CONTROL STATUS REGISTER (CSR) 
START OF CSR BIT DEFINITIONS 
DRIVE READY 
FUNCTION CODE 

BUS ADDRESS EXTENSION BITS 
INTERRUPT ENABLE 
CONTROLLER READY 
DRIVE SELECT 
OPERATION INCOMPLETE 
DATA CRC OR HEADER CRC 
DATA LATE OR HEADER NOT FOUND 
NON-EXISTENT MEMORY 
DRIVE ERROR 
COMPOSITE ERROR 
END CSR BIT DEFINITIONS 






A Sample Q-Bus Driver 


$DEF 

$DEF 


$DEF 


$DEF 


RL_BA 

RL_DA 


RL_MP 


.BLKW 1 

BUS ADDRESS REGISTER (BAR) 

.BLKW 1 

DISK ADDRESS REGISTER (DAR) 

RL_DA,0,<- 

START OF DAR BIT DEFINITIONS 

<MRK,,M>,- 

MARK (ALWAYS 1) 

<STS,,M>,- 

GET STATUS 


RESERVED BIT 

<RST,, M>, - 

RESET 

<,12> t - 

RESERVED BITS 

END OF DAR BIT DEFINITIONS 

.BLKW 1 

MULTIPURPOSE REGISTER (MPR) 

RL_MP,0,<- 

START OF MPR BIT DEFINITIONS 

<STA,3>,- 

DRIVE STATE 

<BH,,M>,- 

BRUSH HOME 

<HO,,M>,- 

HEADS OUT 

<CO f ,M>,- 

COVER OPEN 

<HS,,M>,- 

HEAD SELECT 

<TYP,,M>,- 

DRIVE TYPE 

<DSE,,M>,- 

DRIVE SELECT ERROR 

<VC,,M>,- 

VOLUME CHECK 

<WGE,, M>, - 

WRITE GATE ERROR 

<SPE,,M>,- 

SPIN ERROR 

<SKTO,,M>,- 

SEEK TIME OUT 

<WL.,M>,- 

WRITE LOCK 

<CHE,,M>,- 

CURRENT HEAD ERROR 

<WDE,,M>- 

WRITE DATA ERROR 


RL.BAE 
SDEFEND RL 


.BLKW 


BUS ADDRESS EXTENSION REGISTER(BAE) 
END RLll/RLOl REGISTER DEFINITIONS 


HARDWARE FUNCTION CODES 


F_N0P=0*2 

F_UNLOAD=F_NOP 

F_SEEK=3*2 


NO OPERATION 
NO OPERATION 
SEEK CYLINDER 


F_RECAL=F_NOP 

F_DRVCLR=2*2 

F_RELEASE=F_NOP 

F_OFFSET=F_NOP 

F_RETCENTER=F_NOP 

F_PACKACK=2*2 

F_SEARCH=F_NOP 

F_WRITECHECK=1*2 

F_WRITEDATA=5*2 

F_WRITEHEAD=F_NOP 

F_READDATA=6*2 

F_READHEAD=4*2 

F_AVAILABLE=F_NOP 

F_GETSTATUS=2*2 


NO OPERATION 

DRIVE CLEAR (GET STATUS) 

NO OPERATION 
NO OPERATION 
NO OPERATION 

PACK ACKNOWLEDGE (SET VOLUME VALID) 

NO OPERATION 

WRITE CHECK 

WRITE DATA 

NO OPERATION 

READ DATA 

READ HEADER 

NO OPERATION 

GET STATUS (DRIVER INTERNAL USE) 
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.PAGE 

.SBTTL STANDARD TABLES 


DRIVER PROLOGUE TABLE 

THE DPT DESCRIBES DRIVER PARAMETERS AND I/O DATABASE FIELDS 
THAT ARE TO BE INITIALIZED DURING DRIVER LOADING AND RELOADING 


DPTAB 


END=DL_END,- 
ADAPTER=UBA,- 
FLAGS=DPT$M_SVP,- 
UCBSIZE=UCB$K_DL_LEN,- 
NAME=DLDRIVER 


DPT CREATION MACRO 

END OF DRIVER LABEL 

ADAPTER TYPE = UNIBUS 

SYSTEM PAGE TABLE ENTRY REQUIRED 

LENGTH OF UCB 

DRIVER NAME 


DPT.STORE INIT ;START CONTROL BLOCK INIT VALUES 

DPT.STORE DDB,DDB$L_ACPD,L,< ~A\F11\> ;DEFAULT ACP NAME 

DPT.STORE DDB,DDB$L_ACPD+3,B,DDB$K_CART ;ACP CLASS 


DPT.STORE UCB,UCB$B_FIPL,B,8 
DPT_STORE UCB,UCB$L_DEVCHAR,L,- 
<DEV$M_FOD- 
!DEV$M_DIR- 
!DEV$M_AVL- 
!DEV$M_ELG- 
!DEV$M_SHR- 
!DEV$M_IDV- 
!DEV$M_ODV- 
!DEV$M_RND> 

DPT.STORE UCB,UCB$L_DEVCHAR2,L,- 


FORK IPL 

DEVICE CHARACTERISTICS 
FILES ORIENTED 
DIRECTORY STRUCTURED 
AVAILABLE 
ERROR LOGGING 
SHAREABLE 
INPUT DEVICE 
OUTPUT DEVICE 
RANDOM ACCESS 
DEVICE CHARACTERISTICS 
PREFIX NAME WITH "node$" 


<DEV$M_NNM> 

DPT_STORE UCB,UCB$B_DEVCLASS,B,DC$_DISK ;DEVICE CLASS 
DPT_STORE UCB,UCB$W_DEVBUFSIZ,W,512 ;DEFAULT BUFFER SIZE 

DPT.STORE UCB,UCB$B_SECTORS,B,40 ;NUMBER OF SECTORS PER TRACK 


DPT.STORE UCB,UCB$B_TRACKS,B,2 
DPT_STORE UCB,UCB$B_DIPL,B,21 
DPT.STORE UCB f UCB$B_ERTMAX,B,8 
DPT.STORE UCB,UCB$W_DEVSTS,W,- 
<UCB$M_NOCNVRT> 

DPT.STORE REINIT ;START CONTROL BLOCK RE-INIT VALUES 

DPT_STORE CRB,CRB$L_INTD+4,D,DL_INT ;INTERRUPT SERVICE ROUTINE ADDRESS 


NUMBER OF TRACKS PER CYLINDER 
DEVICE IPL 

MAX ERROR RETRY COUNT 

INHIBIT LOG TO PHYS CONVERSION IN FDT 


DPT.STORE CRB,CRB$L_INTD+VEC$L_INITIAL,- 
D,DL_RL11_INIT 

DPT.STORE CRB,CRB$L_INTD+VEC$L_UNITINIT,- 
D,DL_RLOX_INIT 

DPT.STORE DDB,DDB$L_DDT,D,DL$DDT 


CONTROLLER INIT ADDRESS 


UNIT INIT ADDRESS 


DDT ADDRESS 


DPT.STORE END 


;END OF INITIALIZATION TABLE 
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DRIVER DISPATCH TABLE 

THE DDT LISTS ENTRY POINTS FOR DRIVER SUBROUTINES WHICH ARE 
CALLED BY THE OPERATING SYSTEM. 

DDTAB 

DEVNAM=DL,- 
START=DL_STARTIO,- 
UNSOLIC=DL_UNSOLNT,- 
FUNCTB=DL_FUNCTABLE,- 
CANCEL=0,- 
REGDMP=DL_ REGDUMP,- 
DIAGBF=«RL_NUM_REGS+5+5+3+l>*4> , - ; BYTES IN DIAG BUFFER 

ERLGBF=«<RL_NUM_REGS+5+l>*4>+EMB$L_DV_REGSAV> ; BYTES IN 

;ERROR LOG BUFFER 

DIAGNOSTIC BUFFER SIZE = «4 RL02 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS 

+ 5 IOCSDIAGBUFILL LONGWORDS + 3 BUFFER ALLOCATION 
LONGWORDS + 1 LONGWORD FOR # REGISTERS IN DL_REGDUMP> 

* 4 BYTES/LONGWORD> 

ERROR LOG BUFFER SIZE = «<4 RL02 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS 

+ 1 LONGWORD FOR # REGISTERS IN DL_REGDUMP> 

* 4 BYTES/LONGWORD> + BYTES NEEDED FOR ERROR LOGGER 
TO SAVE SOFTWARE REGISTERS> 


DDT CREATION MACRO 
NAME OF DEVICE 
START I/O ROUTINE 
UNSOLICITED INTERRUPT 
FUNCTION DECISION TABLE 
CANCEL=NO-OP FOR FILES DEVICE 
REGISTER DUMP ROUTINE 


HARDWARE FUNCTION CODE TABLE 


FTAB: 


THIS TABLE MERGES THE FUNCTION CODE BITS WITH THE 
INTERRUPT ENABLE BIT AND GENERATES THE CASE TABLE 
INDEX SYMBOL. 


GENF 

F_NOP 

NO-OP 

GENF 

F.UNLOAD 

UNLOAD VOLUME (NOP) 

GENF 

F.SEEK 

SEEK 

GENF 

F.RECAL 

RECALIBRATE (NOP) 

GENF 

F.DRVCLR 

DRIVE CLEAR (RESET & GET STATUS) 

GENF 

F.RELEASE 

RELEASE PORT (NOP) 

GENF 

F.OFFSET 

OFFSET HEADS (NOP) 

GENF 

F.RETCENTER 

RETURN HEADS TO CENTERLINE (NOP) 

GENF 

F.PACKACK 

PACK ACKNOWLEDGE (RESET & GET STATUS) 

GENF 

F_SEARCH 

SEARCH (NOP) 

GENF 

F_WRITECHECK 

WRITE CHECK 

GENF 

F.WRITEDATA 

WRITE DATA 

GENF 

F.READDATA 

READ DATA 

GENF 

F.WRITEHEAD 

WRITE HEADERS (NOP) 

GENF 

F.READHEAD 

READ HEADERS 

GENF 

F_NOP 

place holder 

GENF 

F_NOP 

place holder 

GENF 

F_AVAILABLE 

AVAILABLE 
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FUNCTION DECISION TABLE 

THE FDT LISTS VALID FUNCTION CODES, SPECIFIES WHICH 
CODES ARE BUFFERED, AND DESIGNATES SUBROUTINES TO 
PERFORM PREPROCESSING FOR PARTICULAR FUNCTIONS. 


DL.FUNCTABLE: 

FUNCTAB 



<NOP,- 
UNLOAD,- 
SEEK,- 
DRVCLR,- 
PACKACK,- 
SENSECHAR,- 
SETCHAR,- 
SENSEMODE,- 
SETMODE,- 
WRITECHECK,- 
READHEAD,- 
READLBLK,- 
WRITELBLK,- 
READPBLK,- 
WRITEPBLK,- 
READVBLK,- 
WRITEVBLK,- 
AVAILABLE,- 
ACCESS,- 
ACPCONTROL,- 
CREATE,- 
DEACCESS,- 
DELETE,- 
MODIFY,- 
MOUNT- 
> 


FUNCTAB ,- 



<NOP,- 
UNLOAD,- 
SEEK,- 
DRVCLR,- 
PACKACK,- 
SENSECHAR,- 
SETCHAR,- 
SENSEMODE,- 
SETMODE,- 
AVAILABLE,- 
ACCESS.- 
ACPCONTROL,- 
CREATE,- 
DEACCESS,- 
DELETE,- 
MODIFY,- 
MOUNT- 
> 


LIST LEGAL FUNCTIONS 
NO-OP 
UNLOAD 
SEEK 

DRIVE CLEAR 
PACK ACKNOWLEDGE 
SENSE CHARACTERISTICS 
SET CHARACTERISTICS 
SENSE MODE 
SET MODE 
WRITE CHECK 
READ HEADER 
READ LOGICAL BLOCK 
WRITE LOGICAL BLOCK 
READ PHYSICAL BLOCK 
WRITE PHYSICAL BLOCK 
READ VIRTUAL BLOCK 
WRITE VIRTUAL BLOCK 
AVAILABLE 

ACCESS FILE / FIND DIRECTORY ENTRY 
ACP CONTROL FUNCTION 
CREATE FILE AND/OR DIRECTORY ENTRY 
DEACCESS FILE 

DELETE FILE AND/OR DIRECTORY ENTRY 
MODIFY FILE ATTRIBUTES 
MOUNT VOLUME 

BUFFERED FUNCTIONS 
NO-OP 
UNLOAD 
SEEK 

DRIVE CLEAR 

PACK ACKNOWLEDGE 

SENSE CHARACTERISTICS 

SET CHARACTERISTICS 

SENSE MODE 

SET MODE 

AVAILABLE 

ACCESS FILE / FIND DIRECTORY ENTRY 
ACP CONTROL FUNCTION 
CREATE FILE AND/OR DIRECTORY ENTRY 
DEACCESS FILE 

DELETE FILE AND/OR DIRECTORY ENTRY 
MODIFY FILE ATTRIBUTES 
MOUNT VOLUME 
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FUNCTAB DL_ALIGN,- 
<READHEAD,- 
READLBLK,- 
READPBLK,- 
READVBLK,- 
WRITECHECK,- 
WRITELBLK,- 
WRITEPBLK,- 
WRITEVBLK- 
> 

FUNCTAB +ACP$READBLK,- 
<READHEAD,- 
READLBLK,- 
READPBLK,- 
READVBLK- 
> 

FUNCTAB +ACPSWRITEBLK,- 
<WRITECHECK,- 
WRITELBLK,- 
WRITEPBLK,- 
WRITEVBLK- 
> 

FUNCTAB +ACP$ACCESS,- 
<ACCESS.- 
CREATE- 
> 

FUNCTAB +ACP$DEACCESS,- 
<DEACCESS- 
> 

FUNCTAB +ACP$MODIFY,- 
<ACPCONTROL,- 
DELETE,- 
MODIFY- 
> 

FUNCTAB +ACP$MOUNT,- 
<MOUNT- 
> 

FUNCTAB +EXE$LCLDSKVALID,- 
<UNLOAD,- 
AVAILABLE,- 
PACKACK- 

> 

FUNCTAB +EXE$ZEROPARM,- 
<NOP,- 
UNLOAD,- 
DRVCLR,- 
PACKACK,- 
AVAILABLE,- 
> 

FUNCTAB +EXE$ONEPARM,- 
<SEEK- 
> 

FUNCTAB +EXE$SENSEMODE,- 
<SENSECHAR,- 
SENSEMODE- 
> 


TEST ALIGNMENT FUNCTIONS 
READ HEADER 
READ LOGICAL BLOCK 
READ PHYSICAL BLOCK 
READ VIRTUAL BLOCK 
WRITE CHECK 
WRITE LOGICAL BLOCK 
WRITE PHYSICAL BLOCK 
WRITE VIRTUAL BLOCK 

;READ FUNCTIONS 
; READ HEADER 
; READ LOGICAL BLOCK 
; READ PHYSICAL BLOCK 
; READ VIRTUAL BLOCK 

;WRITE FUNCTIONS 
; WRITE CHECK 
; WRITE LOGICAL BLOCK 
; WRITE PHYSICAL BLOCK 
; WRITE VIRTUAL BLOCK 

;ACCESS FUNCTIONS 

; ACCEESS FILE / FIND DIRECTORY ENTRY 
; CREATE FILE AND/OR DIRECTORY ENTRY 

;DEACCESS FUNCTION 
; DEACCESS FILE 

;MODIFY FUNCTIONS 
; ACP CONTROL FUNCTION 
; DELETE FILE AND/OR DIRECTORY ENTRY 
; MODIFY FILE ATTRIBUTES 

;MOUNT FUNCTION 
; MOUNT VOLUME 

;LOCAL DISK VALID FUNCTIONS 
;UNLOAD VOLUME 
;UNIT AVAILABLE 
;PACK ACKNOWLEDGE 

;ZERO PARAMETER FUNCTIONS 
; NO-OP 
; UNLOAD 
; DRIVE CLEAR 
; PACK ACKNOWLEDGE 
; AVAILABLE 

;ONE PARAMETER FUNCTION 
; SEEK 

;SENSE FUNCTIONS 
; SENSE CHARACTERISTICS 
; SENSE MODE 
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FUNCTAB +EXE$SETCHAR,- 
<SETCHAR,- 
SETMODE- 
> 

.PAGE 


SET FUNCTIONS 
SET CHARACTERISTICS 
SET MODE 


.SBTTL CONTROLLER INITIALIZATION ROUTINE 


++ 

FUNCTIONAL DESCRIPTION: 


THIS ROUTINE IS A NO-OP FOR THE RL11 BUT MUST BE INCLUDED 
SINCE IT IS CALLED WHEN THE RL02 IS BOOTED AS A SYSTEM DEVICE. 

THE OPERATING SYSTEM CALLS THIS ROUTINE: 

- AT SYSTEM STARTUP 

- DURING DRIVER LOADING 

- DURING RECOVERY FROM POWER FAILURE 


INPUTS: 

R4 - CSR ADDRESS (DEVICE CONTROL STATUS REGISTER) 

R5 - IDB ADDRESS (INTERRUPT DATA BLOCK) 

R6 - DDB ADDRESS (DEVICE DATA BLOCK) 

R8 - CRB ADDRESS (CHANNEL REQUEST BLOCK) 

ALL INTERRUPTS ARE LOCKED OUT 

OUTPUTS: 

ALL REGISTERS EXCEPT R0-R3 ARE PRESERVED. 

CONTROL IS RETURNED TO THE CALLER. 


DL_RL11_INIT: ;CONTROLLER INITIALIZATION 

; FOR MICROVAX I, ALLOCATE A PHYSICALLY CONTIGUOUS BUFFER 



; AREA 

FOR PERFORMING I/O. 



CPUDISP 

A 

A 

-4 

CO 

o 

to 

o 

m 

V 

i 




<785,20$>,- 
<780,20$>, - 
<750,20$>,- 
<730,20$>,- 
<UV1,10$» 

FOR MICROVAX I, ALLOCATE BUFFER AREA 
FOR ALL OTHERS, SKIP BUFFER AREA 

10$: 

MOVZWL 

#UCB$K_DL_BUFSZ,R1 

LOAD SIZE OF BUFFER 


JSB 

G ~ EXE$ALOPHYCNTG 

ALLOCATE PHYSICALLY-CONTIGUOUS MEMORY 


BLBC 

RO,20$ 

EXIT ON ERROR 


MOVL 

R2,CRB$L_AUXSTRUC(R8) 

GET BUFFER VIRTUAL ADDRESS 


RSB 


RETURN TO CALLER 

20$: 

CLRL 

CRB$L_AUXSTRUC(R8) 

INDICATE MEMORY ALLOCATION FAILURE 


RSB 


RETURN TO CALLER 
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.PAGE 

.SBTTL UNIT INITIALIZATION ROUTINE 

++ 

DL_RLOX_INIT - UNIT INITIALIZATION ROUTINE 
FUNCTIONAL DESCRIPTION: 

THIS ROUTINE READIES THE RL01/RL02 UNITS FOR I/O OPERATIONS. 

THE OPERATING SYSTEM CALLS THIS ROUTINE: 

- AT SYSTEM STARTUP 

- DURING DRIVER LOADING 

- DURING RECOVERY FROM POWER FAILURE 

INPUTS: 

R4 - CSR ADDRESS (CONTROLLER STATUS REGISTER) 

R5 - UCB ADDRESS (UNIT-CONTROL BLOCK) 

OUTPUTS: 

THE DRIVE UNIT IS RESET, UCB FIELDS ARE INITIALIZED, AND THE 
ROUTINE WAITS FOR ONLINE UNITS TO SPIN UP. ALL REGISTERS 
EXCEPT R0-R3 ARE PRESERVED. 


DL_RLOX_INIT: 

MOVW #1(9UCB$V_DL_MAPPING, - 
UCB$W_DL_FLAGS(R5) 


RL01/RL02 UNIT INITIALIZATION 
DEFAULT TO ADAPTER MAPPING 
AND 18 BIT ADDRESSING 


; SET CPU DEPENDENT UCB FLAGS FOR DL 

CPUDISP <<790,10$>,- 
<785,10$>,- 
<780,10$>,- 
<750,10$>,- 
<730,10$>,- 
<UV1,5$» 

5$: MOVW #1@UCB$V_DL_22BIT,- ; FOR MICROVAX I 22 BIT 

UCB$W_DL_FLAGS(R5) ; ADDRESSING AND NO ADAPTER MAPPING 

10$: MOVZWL UCB$W_STS(R5),R3 ;SAVE CURRENT UNIT STATUS 

BICW #UCB$M_ONLINE!UCB$M_VALID,- ;ASSUME OFFLINE/INVALID 

UCB$W_STS(R5) 


WAIT FOR CONTROLLER (6 SECONDS MAX) IF CHANNEL IS BUSY WITH ANOTHER UNIT 


MOVL UCB$L_CRB(R5),R0 ;GET CRB ADDRESS 

BBC #CRB$V_BSY,CRB$B_MASK(RO),20$ ;IF CLEAR, CHANNEL NOT BUSY 

TIMEDWAIT TIME=#600*1000,- ;6 SECOND WAIT LOOP 

INS1=<TSTB RL_CS(R4)>,- ;IS CONTROLLER READY 

INS2=<BLSS 15$>,- ;IF LSS, YES 

D0NELBL=15$ ;LABEL TO EXIT WAIT LOOP 

BLBC RO,25$ ;TIME EXPIRED - EXIT 
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GET CURRENT DRIVE STATUS AND RESET DRIVE 


20 $: 


MOVW 

CLRL 

INSV 

BISW3 

BSBW 

TSTB 

BGEQ 


#RL_DA_M_RST!- ;PUT RESET AND GET STATUS IN DAR 

RL_DA_M_STS!RL_DA_M_MRK,RL_DA(R4) ;... 

R1 ;CLEAR R1 FOR UNIT NUMBER 

UCB$W_UNIT(R5),#8,#8,R1 ;GET UNIT NUMBER 
R1,#F_GETSTATUS,RL_CS(R4) ;EXECUTE GET STATUS FUNCTION 


DL.WAIT 

RL_CS(R4) 

25$ 


WAIT FOR CONTROLLER 
WAS CONTROLLER READY? 
IF GEQ, NO 


CLASSIFY DRIVE TYPE 



MOVL 


BITW 

BNEQ 

MOVB 


MOVW 

MOVZWL 

BRB 

25$: 

BRB 

30$: 

MOVB 


MOVW 

MOVZWL 

INCL 

40$: 

BBC 


SET MEDIA IDENT "DL RL01" 
IS DRIVE TYPE = RL02? 

IF NEQ, YES 


#~X2324C001,- 
UCB$L_MEDIA_ID(R5) 

#RL_MP_M_TYP,RL_MP(R4) 

30$ 

S~#DT$_RL01,- 

UCB$B_DEVTYPE(R5) ;SET RL01 DEVICE TYPE 

#256,UCB$W_CYLINDERS(R5);SET NUMBER OF RL01 CYLINDERS 
#10240,UCB$L_MAXBL0CK(R5) ;SET MAX RL01 BLOCK NUMBER 
40$ 


70$ ;BRANCH TO COMMON EXIT 

S~#DT$_RL02,- 

UCB$B_DEVTYPE(R5) ;SET RL02 DEVICE TYPE 

#512,UCB$W_CYLINDERS(R5);SET NUMBER OF RL02 CYLINDERS 
#20480,UCB$L_MAXBL0CK(R5) ;SET MAX RL02 BLOCK NUMBER 
UCB$L_MEDIA_ID(R5) ;SET MEDIA IDENT "DL RL02" 

#UCB$V_VALID,R3,60$ ; Branch around wait for drive to spinup 

; if the drive did NOT have a VALID 
; volume on it before POWER failure. 


INITIALIZE UCB FIELDS AND WAIT FOR ONLINE UNITS TO SPIN UP 


45$: 


50$: 


BITW #RL_CS_M_DRDY,RL_CS(R4) 
BNEQ 50$ 

JSB G~EXE$PWRTIMCHK 

BLBS RO,45$ 

BRB 60$ 

BISW 


Is drive ready? 

IF NEQ, YES 

IS MAX TIME EXCEEDED? 

IF LBS, NO, MORE TIME NEEDED 
POWER UP TIME EXCEEDED 


#UCB$M_VALID,UCB$W_STS(R5) ;SET UCB STATUS VOLUME VALID 
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60$: 


65$: 

70$: 


BBS 

MOVL 

MOVL 

BEQL 

MOVL 

EXTZV 

MOVL 

MOVL 

BICL3 

ASSUME 

INSV 

MOVL 

BISW 

RSB 

.PAGE 

.SBTTL 


#UCB$V_DL_MAPPING,- 
UCB$W_DL_FLAGS(R5),65$ 
UCB$L_CRB(R5),R1 
CRB$L_AUXSTRUC(R1),R2 
70$ 

R2,UCB$A_DL_BUF_VA(R5) 


ADAPTER MAPPING? 

IF BS, YES 
GET CRB ADDRESS 

MEMORY ALLOC FAILURE DURING CTL INIT? 
IF EQL, YES, LEAVE OFFLINE 
SAVE BUFFER'S VIRTUAL ADDRESS 


#VA$V_VPN,#VA$S_VPN,R2,R1;GET VIRTUAL PAGE NUMBER OF BUFFER 


G~MMG$GL_SPTBASE.RO 
(RO) [Rl] , RO 
#~C<VA$M_BYTE>.R2,Rl 
PTE$S_PFN GE 13 
RO,#9,#13,Rl 
Rl,UCB$A_DL_BUF_PA(R5) 


GET BASE ADDRESS OF SPTS 

GET THE PTE CONTENTS 

GET BUFFER OFFSET (BA00-BA08) 

;COPY BA09-BA21 

;SAVE PHYSICAL ADDRESS OF BUFFER 


#UCB$M_0NLINE,UCB$W_STS(R5) ;SET UCB STATUS VOLUME VALID 


DRIVER SPECIFIC SUBROUTINES 


DL.WAIT - WAIT FOR CONTROLLER READY 


INPUTS: 

R4 


- DEVICE CSR ADDRESS 


FUNCTIONAL DESCRIPTION: 

THIS ROUTINE IS CALLED FROM THE DRIVER UNIT INITIALIZATION ROUTINE 
TO WAIT UNTIL THE RL11 CONTROLLER IS READY. TO PREVENT HANGING UP 
AT HIGH IPL, A MAXIMUM OF 30 USEC ELAPSES BEFORE CONTROL IS 
RETURNED TO THE CALLER. 



DL.WAIT: 


MOVQ RO,-(SP) 

DSBINT 
TIMEWAIT 
ENBINT 

MOVQ (SP) +,R0 

RSB 


#3,#RL_CS_M_CRDY 


WAIT FOR CONTROLLER READY 
SAVE RO, Rl 
DISABLE INTERRUPTS 
RL_CS(R4),W 
ENABLE INTERRUPTS 
RESTORE RO, Rl 

RETURN TO UNIT INIT OR STARTIO 


.PAGE 

.SBTTL FDT ROUTINE - TEST TRANSFER BYTE COUNT ALIGNMENT 


++ 


DL_ALIGN - FDT ROUTINE TO TEST XFER BYTE COUNT 
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FUNCTIONAL DESCRIPTION: 


THIS ROUTINE IS CALLED FROM THE FUNCTION DECISION TABLE DISPATCHER 
TO CHECK THE BYTE COUNT PARAMETER SPECIFIED BY THE USER PROCESS 
FOR AN EVEN NUMBER OF BYTES (WORD BOUNDARY). 


INPUTS: 


R3 

R4 

R5 

R6 

R7 

R8 

4(AP) 


IRP ADDRESS (I/O REQUEST PACKET) 

PCB ADDRESS (PROCESS CONTROL BLOCK) 

UCB ADDRESS (UNIT-CONTROL BLOCK) 

CCB ADDRESS (CHANNEL CONTROL BLOCK) 

BIT NUMBER OF THE I/O FUNCTION CODE 
ADDRESS OF FDT TABLE ENTRY FOR THIS ROUTINE 
ADDRESS OF FIRST FUNCTION DEPENDENT QIO PARAMETER 


OUTPUTS: 

IF THE QIO BYTE COUNT PARAMETER IS ODD, THE I/O OPERATION IS 
TERMINATED WITH AN ERROR. IF IT IS EVEN, CONTROL IS RETURNED 
TO THE FDT DISPATCHER. 


CHECK BYTE COUNT AT PI(AP) 
IF LBS, ODD BYTE COUNT 
EVEN - RETURN TO CALLER 
SET BUFFER ALIGNMENT STATUS 
ABORT I/O 



# 


DL.ALIGN: 

BLBS 

RSB 

10$: MOVZWL 

JMP 


4(AP),10$ 

#SS$_IVBUFLEN,RO 
G~EXE$ABORT10 
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.PAGE 

.SBTTL START I/O ROUTINE 


++ 

DL.STARTIO - START I/O ROUTINE 
FUNCTIONAL DESCRIPTION: 

THIS FORK PROCESS IS ENTERED FROM THE EXECUTIVE AFTER AN I/O REQUEST 
PACKET HAS BEEN DEQUEUED, AND PERFORMS THE FOLLOWING: 

- ACTIVATES THE DISK AFTER SETTING UCB FIELDS, OBTAINING 
UBA AND CONTROLLER RESOURCES, AND SETTING RL11 REGISTERS 

- WAITS FOR AN INTERRUPT 

- REGAINS CONTROL AFTER THE ISR SERVICES THE INTERRUPT, AND 

- RE-ACTIVATES THE DISK IF THE ORIGINAL FUNCTION 
IS NOT YET COMPLETE, OR 

- COMPLETES THE I/O REQUEST BY RELEASING RESOURCES, 
SETTING STATUS CODES, AND RETURNING TO THE EXECUTIVE. 

INPUTS: 

R3 - IRP ADDRESS (I/O REQUEST PACKET) 

R5 - UCB ADDRESS (UNIT-CONTROL BLOCK) 

IRP$L_MEDIA - PARAMETER LONGWORD (LOGICAL BLOCK NUMBER) 

OUTPUTS: 

RO - FIRST I/O STATUS LONGWORD: STATUS CODE & BYTES XFERED 

R1 - SECOND I/O STATUS LONGWORD: 0 FOR DISKS 

THE I/O FUNCTION IS EXECUTED. 

ALL REGISTERS EXCEPT R0-R4 ARE PRESERVED. 


DL.STARTIO: ;START I/O OPERATION 


COMPUTE PHYSICAL MEDIA ADDRESS 

LBN = LBN * (SECTORS/BLOCK) 

LBN/(SECTORS/TRACK) = D + SECTOR 
D/(TRACKS/CYLINDER) = CYLINDER + TRACK 
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PREPROCESS UCB FIELDS 


PREPROCESS: 

MOVL 

BBS 

MULL3 

MOVZBL 

CLRL 

EDIV 

MOVZBL 

EDIV 

MOVB 

MOVW 

10 $: 

MOVB 

MNEGW 

CLRW 

CLRB 

MOVW 

EXTZV 

MOVB 

CMPB 

BNEQ 

MOVW 


IRP$L_MEDIA(R3),- 
UCB$L_MEDIA(R5) 
#IRP$V_PHYSIO,- 
IRP$W_STS(R3),10$ 

#2,UCB$L_MEDIA(R5),R0 
UCB$B_SECTORS(R5),R2 
R1 

R2.R0.R0,UCB$L_MEDIA(R5) 
UCB$B_TRACKS(R5),R2 
R2.R0.R0,R1 
R1,UCB$L_MEDIA+1(R5) 

RO,UCB$L_MEDIA+2(R5) 


Copy given MEDIA address (logical) 
to the UCB. 

IF SET, PHYSICAL I/O 

SCALE LBN IN RO 

GET NUMBER OF SECTORS PER TRACK 
CLEAR HIGH PART OF DIVIDEND 
CALCULATE SECTOR NUMBER AND STORE 
GET NUMBER OF TRACKS PER CYLINDER 
CALCULATE TRACK AND CYLINDER 
STORE TRACK NUMBER 
STORE CYLINDER NUMBER 


UCB$B_ERTMAX(R5),- 
UCB$B_ERTCNT(R5) ;... 

UCB$W_BCNT(R5),UCB$W_BCR(R5) 


;INITIALIZE ERROR RETRY COUNT 


; INIT NEG BYTES LEFT TO XFER 


CLEAR DATA-PATH NO. FOR USE AS A 
UBA-RESOURCE-ALLOCATION FLAG 
CLEAR DATA-PATH-PURGE-ERROR REGISTER 


UCB$W_DL_DPN(R5) 

UCB$B_DL_DPPE(R5) 

IRP$W_FUNC(R3),UCB$W_FUNC(R5) ;SAVE FUNCTION CODE 
#IRP$V_FCODE,- ;EXTRACT I/O FUNCTION CODE 

#IRP$S_FCODE,IRP$W_FUNC(R3),R1 ;... 


R1,UCB$B_FEX(R5) 

#I0$_SEEK,R1 

20 $ 

IRP$L_MEDIA(R3),- 
UCB$W_DC(R5) 


STORE FUNCTION DISPATCH INDEX 
SEEK FUNCTION? 

IF NEQ, NO 

STORE CYLINDER ADDRESS 


20 $: 

BICW #UCB$M_DIAGBUF,- 

UCB$W_DEVSTS(R5) ;CLR DIAGNOSTIC BUFFER PRESENT 

BBC #IRP$V_DIAGBUF,- ;IF CLR, NO DIAG BUFFER 

IRP$W_STS(R3),FDISPATCH ;... 

BISW #UCB$M_DIAGBUF,UCB$W_DEVSTS(R5) ;SET DIAG BUFFER PRESENT 
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CENTRAL FUNCTION DISPATCH 


FDISPATCH: 

MOVL 

UCB$L_IRP(R5),R3 

BBS 

#IRP$V_PHYSIO,- 
IRP$W_STS(R3),10$ 

BBS 

#UCB$V_VALID,- 
UCB$W_STS(R5),10$ 

MOVZWL 

#SS$_VOLINV,RO 

BRW 

RESETXFR 

10$: CLRB 

UCB$B_DL_DCHEK(R5) 

MOVZBL 

UCB$B_FEX(R5),R3 

CASE 

R3,<- 
UNLOAD,- 
SEEK,- 
NOP,- 
DRVCLR,- 
NOP,- 
NOP,- 
NOP,- 
PACKACK,- 
NOP,- 

WRITECHECK,- 
WRITEDATA,- 
READDATA,- 
NOP,- 

READHEAD,- 

NOP,- 

NOP,- 

AVAILABLE- 
>,LIMIT=#CDF_UNLOAD 

NOP: 

SEEK: 

DRVCLR: 

DO.FUNCTION: 

EXFUNCL 

RETRYERR 

BRB 

NORMAL 

PACKACK: 

BISW 

#UCB$M_VALID, - 
UCB$W_STS(R5) 

BRB 

DO.FUNCTION 

UNLOAD: 

AVAILABLE: 

BICW 

#UCB$M_VALID, - 
UCB$W_STS(R5) 

BRB 

NORMAL 


FUNCTION DISPATCH 

GET IRP ADDRESS 

IF SET, PHYSICAL I/O FUNCTION 

IF SET, VOLUME SOFTWARE VALID 

SET VOLUME INVALID STATUS 
RESET BYTE COUNT AND EXIT 
CLEAR DATA CHECK IN PROGRESS 
GET FUNCTION DISPATCH INDEX 
DISPATCH TO FUNCTION HANDLING ROUTINE 
UNLOAD 
SEEK 

RECALIBRATE (unsupported) 

DRVCLR 

RELEASE PORT (unsupported) 

OFFSET HEADS (unsupported) 

RETURN TO CENTER (unsupported) 

PACK ACKNOWLEDGE 
SEARCH (unsupported) 

WRITE CHECK 
WRITE DATA 
READ DATA 

WRITE HEADER (unsupported) 

READ HEADER 
place holder 
place holder 
AVAILABLE 


NO-OP 

SEEK 

DRIVE CLEAR (GET STATUS & RESET) 

;EXECUTE FUNCTION - RETRY IF FAILURE 
;SUCCESSFUL - EXIT WITH NORMAL STATUS 

;PACK ACKNOWLEDGE (GET STATUS & RESET) 
;Set software volume valid bit. 

;Then go do hardware function. 

;UNLOAD 
;AVAILABLE 

;Clear software volume valid bit. 

;and go complete operation without 
;any hardware interaction. 
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WRITECHECK: 

READHEAD: 

BICW #IO$M_DATACHECK,- 
UCB$W_FUNC(R5) 

WRITEDATA: 

READDATA: 

EXFUNCL RETRYERR,F_SEEK 

MOVZBL UCB$B_FEX(R5),R3 
EXFUNCL RETRYERR 


OPERATON COMPLETION 


NORMAL: 



MOVZWL 

#SS$_NORMAL,RO 


BRW 

FUNCXT 

RETRYERR: 



DECB 

UCB$B_ERTCNT(R5) 


BEQL 

FATALERR 


BRW 

FDISPATCH 

FATALERR: 



MOVZWL 

#SS$_VOLINV,RO 


BBS 

#RL_MP_V_VC,- 
UCB$W_DL_MP(R5).FUNCXT 


MOVZWL 

#SS$_WRITLCK,RO 


BBC 

#RL_MP_V_WL,- 
UCB$W_DL_MP(R5),5$ 


BBS 

#RL_MP_V_WGE,- 
UCB$W_DL_MP(R5).FUNCXT 

5$: 

MOVZWL 

#SS$_DATACHECK,RO 


TSTB 

UCB$B_DL_DCHEK(R5) 


BEQL 

10$ 


BBS 

#RL_CS_V_OPI,- 
UCB$W_DL_CS(R5),10$ 


BBS 

#RL_CS_V_CRC,- 
UCB$W_DL_CS(R5).FUNCXT 

10$: 

MOVZWL 

#SS$_PARITY,RO 


BBS 

#RL_CS_V_CRC,- 
UCB$W_DL_CS(R5).FUNCXT 

20$: 

MOVZWL 

#SS$_DRVERR,RO 


BBS 

#RL_CS_V_DE,- 
UCB$W_DL_CS(R5).FUNCXT 


MOVZWL 

#SS$_CTRLERR,RO 


WRITE CHECK 
READ HEADER 

CLEAR DATA CHECK REQUEST- 
TO PREVENT EXTRA WRITE CHECK 

WRITE DATA 
READ DATA 

EXECUTE EXPLICIT SEEK - RETRY IF FAIL 

GET FUNCTION DISPATCH INDEX 
EXECUTE TRANSFER FUNCTION 


SUCCESSFUL OPERATION COMPLETE 
SET NORMAL COMPLETION STATUS 
FUNCTION EXIT 

RETRIABLE ERROR 
ANY RETRIES LEFT? 

IF EQL, NO 
RETRY FUNCTION 

UNRECOVERABLE ERROR 
ASSUME VOLUME INVALID STATUS 
IF SET, VOLUME INVALID 

ASSUME WRITE LOCK ERROR STATUS 
IF CLR, VOLUME NOT WRITE LOCKED 

IF SET, WRITE GATE ERROR 

IF WL & WGE SET, WRITE LOCK ERROR 

ASSUME DATA CHECK ERROR STATUS 
WRITE CHECK IN PROGRESS? 

IF EQL, NO 

IF SET, NOT WRITE CHECK ERROR 
IF SET, WRITE CHECK ERROR 

ASSUME PARITY ERROR STATUS 
IF SET, CRC ERROR 
OR DATA-PATH-PURGE ERROR 

ASSUME DRIVE ERROR STATUS 
IF SET, DRIVE ERROR 

ASSUME CONTROLLER ERROR STATUS 
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FUNCXT 

PUSHL 

RO 

FUNCTION EXIT 

SAVE FINAL REQUEST STATUS 


JSB 

G~IOC$DIAGBUFILL 

FILL DIAGNOSTIC BUFFER IF PRESENT 


CMPB 

#CDF_WRITECHECK,UCB$B_FEX(R5) ;DRIVE RELATED FUNCTION? 


BGTRU 

10$ ;IF GTRU, YES 


CMPB 

#CDF_AVAILABLE,UCB$B_FEX(R5) ;DRIVE RELATED FUNCTION? 


BEQL 

10$ 

IF EQL, YES 


MOVL 

UCB$L_IRP(R5),R3 

RETRIEVE ADDRESS OF IRP 


ADDW3 

UCB$W_BCR(R5) 

IRP$W_BCNT(R3),2(SP) 

CALCULATE BYTES TRANSFERRED 


TSTW 

UCB$W_DL_DPN(R5) 

ARE UBA RESOURCES ALLOCATED? 


BEQL 

20$ 

IF EQL, NO 


BBC 

#UCB$V_DL_MAPPING,- 

ADAPTER MAPPING? 



UCB$W_DL_FLAGS(R5),10$ 

IF BC, NO 


RELDPR 


RELEASE DATA PATH 


RELMPR 


RELEASE MAP REGISTERS 


BRB 

20$ 

JOIN COMMON CODE 

10$: 

MOVL 

UCB$L_DL_SVAPTE(R5) 
UCB$L_SVAPTE(R5) 

RESTORE ORIGINAL SVAPTE 

20$: 

RELCHAN 


RELEASE CHANNEL IF OWNED 


CLRL 

R1 

CLEAR SECOND STATUS LONGWORD 


POPL 

RO 

RETRIEVE FINAL REQUEST STATUS 


REQCOM 


COMPLETE REQUEST 


.PAGE 



; FEXL 

- RL11 HARDWARE FUNCTION EXECUTION 

; THIS 

ROUTINE 

IS CALLED VIA A BSB WITH J 

\ BYTE IMMEDIATELY FOLLOWING THAT 


SPECIFIES THE ADDRESS OF AN ERROR ROUTINE. ALL DATA IS ASSUMED TO HAVE BEEN 
SET UP IN THE UCB BEFORE THE CALL. THE APPROPRIATE PARAMETERS ARE LOADED 
INTO DEVICE REGISTERS AND THE FUNCTION IS INITIATED. THE RETURN ADDRESS 
IS STORED IN THE UCB AND A WAITFOR INTERRUPT IS EXECUTED. WHEN THE 
INTERRUPT OCCURS, CONTROL IS RETURNED TO THE CALLER. 
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INPUTS: 

R3 = FUNCTION TABLE DISPATCH INDEX 
R5 = DEVICE UNIT UCB ADDRESS 

00(SP) = RETURN ADDRESS OF CALLER 

04(SP) = RETURN ADDRESS OF CALLER'S CALLER 

IMMEDIATELY FOLLOWING INLINE AT THE CALL SITE IS A BYTE WHICH CONTAINS 
A BRANCH DESTINATION TO AN ERROR RETRY ROUTINE. 

OUTPUTS: 

THERE ARE FOUR EXITS FROM THIS ROUTINE: 


1. SPECIAL CONDITION - THIS EXIT IS TAKEN IF A POWER FAILURE OCCURS 

OR THE OPERATION TIMES OUT. IT IS A JUMP TO THE APPROPRIATE 
ERROR ROUTINE. 

2. FATAL ERROR - THIS EXIT IS TAKEN IF A FATAL CONTROLLER OR DRIVE 

ERROR OCCURS OR IF ANY ERROR OCCURS AND ERROR RETRY IS EITHER 
INHIBITED OR EXHAUSTED. IT IS A JUMP TO THE FATAL ERROR EXIT 
ROUTINE. 

3. RETRIABLE ERROR - THIS EXIT IS TAKEN IF A RETRIABLE CONTROLLER 

OR DRIVE ERROR OCCURS AND ERROR RETRY IS NEITHER INHIBITED 
NOR EXHAUSTED. IT CONSISTS OF TAKING THE ERROR BRANCH EXIT 
SPECIFIED AT THE CALL SITE. 


4. SUCCESSFUL OPERATION - THIS EXIT IS TAKEN IF NO ERRORS OCCUR 
DURING THE OPERATION. IT CONSISTS OF A RETURN INLINE. 


IN ALL CASES IF AN ERROR OCCURS, AN ATTEMPT IS MADE TO LOG THE ERROR. 
IN ALL CASES FINAL DEVICE REGISTERS ARE RETURNED VIA THE UCB. 


FEXL: 


UCB$W_BCR(R5) = NEGATIVE BYTES REMAINING TO TRANSFER 
.PAGE 


POPL UCB$L_DPC(R5) 

MOVB R3,UCB$B_CEX(R5) 

MOVL UCB$L_CRB(R5),R0 

MOVL CRB$L_INTD+VEC$L_IDB(RO) 

CMPL R5,IDB$L_0WNER(R1) 

BNEQ 10$ 

MOVL IDB$L_CSR(R1),R4 

BRB 20$ 


FUNCTION EXECUTOR 

SAVE DRIVER PC VALUE 

SAVE CASE INDEX 

GET ADDRESS OF PRIMARY CRB 

R1 ;GET ADDRESS OF IDB 

DOES THIS PROCESS OWN CHANNEL? 

IF NEQ, NO 

SET ASSIGNED CHANNEL CSR ADDRESS 
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10$: REQPCHAN 

20$: CASE R3,<- 

IMMED,- 
IMMED,- 
POSIT,- 
IMMED,- 
DRCLR,- 
IMMED,- 
IMMED,- 
IMMED,- 
DRCLR,- 
IMMED,- 
> 

BRW XFER 

.PAGE 

; IMMEDIATE FUNCTION EXECUTION 

; FUNCTIONS INCLUDE: 

; NO OPERATION, 

; DRIVE CLEAR, AND 

; PACK ACKNOWLEDGE 

; INPUTS: 


R3 

- CASE INDEX 

R4 

- CSR 

ADDRESS 

R5 

- UCB 

ADDRESS 


FUNCTIONAL DESCRIPTION: 

INTERRUPTS ARE LOCKED OUT, THE APPROPRIATE FUNCTION IS INITIATED WITH 
INTERRUPT ENABLE, AND A WAITFOR INTERRUPT AND KEEP CHANNEL IS EXECUTED. 


REQUEST CHANNEL (RETURNS R4 = CSR ADR) 

DISPATCH TO PROPER FUNCTION ROUTINE 
NO OPERATION 
UNLOAD VOLUME (NOP) 

SEEK CYLINDER 
RECALIBRATE (NOP) 

DRIVE CLEAR (GET STATUS & RESET) 
RELEASE DRIVE (NOP) 

OFFSET HEADS (NOP) 

RETURN TO CENTERLINE (NOP) 

PACK ACKNOWLEDGE 
SEARCH (NOP) 

TRANSFER FUNCTION 


DRCLR: ;DRIVE CLEAR 

BISW #RL_DA_M_STS!- ;SET GETSTATUS,RESET,AND MARK IN DAR 

RL_DA_M_RST!RL_DA_M_MRK,RL DA(R4) ;... 


IMMED: 

CKPWR 

BISW3 R2.FTAB[R3],RL_CS(R4) 

WFIKPCH RETREG,#2 

IOFORK 

BRW RETREG 


IMMEDIATE FUNCTION EXECUTION 
DISABLE INTERRUPTS, CHECK POWER,- 
AND PUT UNIT NUMBER IN R2<9:8> 

MERGE UNIT WITH FNTN AND EXECUTE 
WAITFOR INTERRUPT 
RETURN FROM ISR- 

CREATE FORK PROCESS (&JSB BACK TO ISR) 
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.PAGE 

POSITIONING FUNCTION EXECUTION 
FUNCTIONS INCLUDE: 

SEEK CYLINDER 


INPUTS: 

R3 - CASE INDEX 

R4 - DEVICE CSR ADDRESS 

R5 - UCB ADDRESS 

FUNCTIONAL DESCRIPTION: 

THE CYLINDER DIFFERENCE WORD IS CALCULATED AND LOADED INTO THE DISK 
ADDRESS REGISTER, INTERRUPTS ARE LOCKED OUT, AND THE SEEK FUNCTION 
IS INITIATED WITHOUT INTERRUPT ENABLE. THE CONTROLLER IS THEN POLLED 
FOR READY, AND DEVICE INTERRUPTS ARE ENABLED. 


SINCE THE RL01/RL02 DO NOT ISSUE AN INTERRUPT UPON COMPLETION OF A 
SEEK, OVERLAPPED SEEKS ARE NOT ATTEMPTED, AND ONE OF THE FOLLOWING IS 
PERFORMED. 



IF ONLY A SEEK FUNCTION IS BEING REQUESTED, A DUMMY READ HEADER 
FUNCTION IS ISSUED AND A WAITFOR INTERRUPT IS INITIATED. 

THE READ HEADER IS USED TO SIGNAL THE END OF THE SEEK, SINCE IT 
WILL ISSUE AN INTERRUPT SHORTLY (315 USEC AVG) AFTER THE SEEK IS 
COMPLETE. IT WILL ALSO SENSE FOR A TIMEOUT DURING THE SEEK. 


IF THE SEEK IS ASSOCIATED WITH A DATA TRANSFER REQUEST (RL01/RL02 
TRANSFER FUNCTIONS REQUIRE EXPLICIT SEEKS), THE PROGRAM KEEPS THE 
CHANNEL AND RETURNS TO FDISPATCH TO ISSUE THE TRANSFER REQUEST 
WHILE THE SEEK IS STILL IN PROGREES. WHEN THE SEEK COMPLETES. THE 
RL11 CONTROLLER WILL BEGIN THE TRANSFER. 


POSIT: ;POSITIONING FUNCTION 

; OBTAIN CURRENT DISK ADDRESS 

; IF THERE HAS NOT BEEN A PREVIOUS TRANSFER DURING THIS REQUEST, 

; A READ HEADER IS EXECUTED TO DETERMINE THE CURRENT DISK ADDRESS. 

UCB$W_DL_DPN(R5) ;WAS THERE A PREVIOUS TRANSFER? 

10$ ;IF EQL, NO. READ HEADER 

#~077,UCB$W_DL_DA(R5),R1 ;PUT CURRENT CYL & SURFACE IN R1 
60$ ;CALCULATE DIFFERENCE WORD 



TSTW 

BEQL 

BICW3 

BRW 
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10 $: 

20 $: 


40$: 


50$: 


MOVZBL 

CKPWR 

BISW3 

WFIKPCH 

IOFORK 

BITW 

BEQL 

DECB 

BNEQ 


MOVW 

CKPWR 

BISW3 

WFIKPCH 

IOFORK 

CKPWR 

BISW3 

WFIKPCH 

IOFORK 

BITW 

BEQL 

CLRB 

BRW 


#8,R3 ;SET READ HEADER RETRY COUNT IN R3 

;DISABLE INTERRUPTS, CHECK POWER,- 
;AND PUT UNIT NUMBER IN R2<9:8> 

R2,#F_READHEAD!RL_CS_M_IE,- ;EXECUTE READ HEADER 

RL_CS(R4) ;... 

40$,#2 ;WAIT FOR INTERRUPT OR TIMEOUT 

;CREATE FORK PROCESS 

#RL_CS_M_CE,UCB$W_DL_CS(R5) ;ANY ERRORS? 


50$ 

R3 

20 $ 


#“0200!RL_DA_M_MRK.- 
RL_DA(R4) 


R2,#F_SEEK!RL_CS_M_IE,- 
RL_CS(R4) 

40$,#2 


IF EQL, NO 

DECREMENT READ HEADER RETRY COUNT 

IF NEQ, RETRY READ HEADER 

IF EQL, READ HEADER RETRY EXHAUSTED 

TRY PREVIOUS TRACK 

LOAD REVERSE SEEK DIFFERENCE WORD 

DISABLE INTERRUPTS, CHECK POWER,- 
AND PUT UNIT NUMBER IN R2<9:8> 
EXECUTE REVERSE SEEK 


WAIT FOR SEEK TO BEGIN (INTERRUPT) 
CREATE FORK PROCESS 
DISABLE INTERRUPTS, CHECK POWER,- 
;AND PUT UNIT NUMBER IN R2<9:8> 

R2,#F_READHEAD!RL_CS_M_IE,- ;TRY READ HEADER ON NEW TRACK 

RL_CS(R4) ;... 

40$,#2 ;WAITFOR INTERRUPT OR TIMEOUT 

;CREATE FORK PROCESS 

#RL_CS_M_CE,UCB$W_DL_CS(R5) ;READ HEADER ERROR? 


50$ 

UCB$B_ERTCNT(R5) 

RETREG 


BICW3 #“077,UCB$W_DL_MP(R5),R1 


IF EQL, NO 

CAN NOT READ CURRENT DISK ADDRESS 
CLEAR RETRY COUNT 

FOUND CURRENT DISK ADDRESS 
;PUT CURRENT CYL & SURFACE IN R1 


CALCULATE CYLINDER DIFFERENCE WORD 


60$: 


70 $: 


CLRL 

RO 

INSV 

UCB$W_DA+1(R5),#6,#1,RO 

INSV 

UCB$W_DC(R5),#7,#9,RO 

CMPW 

R0,R1 

BEQL 

80$ 

BICW 

#“0177,R1 

BICW 

#“0177,RO 

SUBW 

R0,R1 

BEQL 

70$ 

BCC 

70$ 

MNEGW 

R1,R1 

BISW 

#4, R1 

INSV 

UCB$W_DA+1(R5),#4,#1,R1 

BISW3 

#RL_DA_M_MRK,R1,RL_DA(R4) 


CLEAR RO FOR DESIRED ADDRESS 

INSERT DESIRED SURFACE IN R0<6> 

INSERT DESIRED CYLINDER IN R0<15:7> 

IS A SEEK NEEDED? 

IF EQL, NO 

REMOVE SURFACE BIT 

REMOVE SURFACE BIT 

SUBTRACT DESIRED FROM ACTUAL 

IF EQL, ONLY CHANGE SURFACE 

IF CC, ACTUAL>=DESIRED 

ACTUAL<DESIRED, MAKE POSITIVE DIFF 

SET SIGN FOR MOVE TO CENTER OF DISK 

INSERT SURFACE BIT 

;SET MARKER AND LOAD DIFFERENCE WORD 
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EXECUTE SEEK 


CKPWR 

BISW3 R2,#F_SEEK!RL_CS_M_IE,- 
RL_CS(R4) 

WFIKPCH 40$,#2 
I0F0RK 

80$: CMPB #IO$_SEEK,UCB$B_FEX(R5) 

BEQL 90$ 


DISABLE INTERRUPTS, CHECK POWER,- 
AND PUT UNIT NUMBER IN R2<9:8> 
EXECUTE SEEK FUNCTION 

WAIT FOR SEEK TO BEGIN (INTERRUPT) 
CREATE FORK PROCESS 
IS SEEK ASSOCIATED WITH A TRANSFER? 
IF EQL, NO, SEEK ONLY 


RETURN FOR SEEK ASSOCIATED WITH A TRANSFER REQUEST 


INCL UCB$L_DPC(R5) 

JMP <3UCB$L_DPC(R5) 

; RETURN FOR SEEK ONLY REQUEST 

90$: CKPWR 

BISW3 R2,#F_READHEAD!RL_CS_M 

RL_CS(R4) 

WFIKPCH RETREG,#2 
IOFORK 

BRW RETREG 


;ADJUST TO CORRECT RETURN ADDRESS 
;RETURN TO DRIVER FOR TRANSFER 


;DISABLE INTERRUPTS, CHECK POWER,- 
;AND PUT UNIT NUMBER IN R2<9:8> 

IE,- ;EXECUTE DUMMY READ HEADER 

;WAIT FOR SEEK TO COMPLETE (INTERRUPT) 
;CREATE FORK PROCESS 
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TRANSFER FUNCTION EXECUTION 

FUNCTIONS INCLUDE: 

WRITE CHECK 
WRITE DATA 
READ DATA, AND 
READ HEADER 


INPUTS: 

R3 - CASE INDEX 

R4 - DEVICE CSR ADDRESS 

R5 - UCB ADDRESS 

FUNCTIONAL DESCRIPTION: 

A UNIBUS DATA PATH IS REQUESTED FOLLOWED BY THE APPROPRIATE NUMBER OF MAP 
REGISTERS REQUIRED FOR THE TRANSFER. THE TRANSFER PARAMETERS ARE LOADED 
INTO THE DEVICE REGISTERS, INTERRUPTS ARE LOCKED OUT, THE FUNCTION IS 
INITIATED, AND A WAITFOR INTERRUPT AND KEEP CHANNEL IS EXECUTED. 

UPON RETURN FROM THE INTERRUPT SERVICE ROUTINE, IF THE TRANSFER IS 
COMPLETE, THE APPROPRIATE EXIT IS TAKEN. IF THE FUNCTION IS NOT COMPLETE 
TRANSFER PARAMETERS ARE UPDATED AND A RETURN TO FDISPATCH IS EXECUTED TO 
RE-ISSUE SEEK AND TRANSFER FUNCTIONS WHILE KEEPING CHANNEL AND UBA 
RESOURCES. IF A DATA CHECK HAS BEEN REQUESTED. IT IS PERFORMED 
BEFORE RETURNING TO FDISPATCH. 


XFER: 


;TRANSFER FUNCTION EXECUTION 
BBS #UCB$V_DL_MAPPING,- ;ADAPTER MAPPING? 

UCB$W_DL_FLAGS(R5),2$ ;BRANCH IF ADAPTER MAPPING. 

MOVW UCB$A_DL_BUF_PA(R5),UCB$W_DL_SBA(R5);GET 1ST WORD OF BUFFER ADDR 
MOVZWL UCB$A_DL_BUF_PA+2(R5),RO;GET BITS 16:21 OF BUFFER ADDRESS 
MOVW R0,RL_BAE(R4) ;SET MEMORY EXTENSION BITS IN BAE 

ASHL #4,RO,RO ;PUT MEMORY EXTENSION BITS IN <5:4> 

MOVB RO,UCB$B_DL_XBA(R5) ;OF CSR 


FIRST TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES 


1 $: 


TSTW 

BNEQ 

CLRL 

CMPB 

BNEQ 

MOVAB 

MOVL 

MNEGW 

BRB 


UCB$W_DL_DPN(R5) 

5$ 

UCB$A_DL_MOVRTN(R5) 
#CDF_WRITEDATA,R3 
1 $ 

G~IOC$MOVFRUSER,- 
UCB$A_DL_MOVRTN(R5) 


;RESOURCES ALREADY ALLOCATED? 

;IF NEQ, YES 
;ASSUME READ 
;WRITE DATA? 

;IF NEQ, NO 

;SET MOVE ROUTINE ADDRESS FOR 
;1ST PARTIAL WRITE 
UCB$L_SVAPTE(R5),UCB$L_DL_SVAPTE(R5);SAVE SVAPTE FOR BUFFER COPY 
#1,UCB$W_DL_DPN(R5) ;SET FIRST XFER FLAG 

5$ ;JOIN COMMON CODE 
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FIRST TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES 


2 $: 


TSTW 

BNEQ 

REQDPR 

REQMPR 

LOADUBA 

MOVL 

EXTZV 

MOVW 


UCB$W_DL_DPN(R5) ;UBA RESOURCES ALREADY ALLOCATED? 

5$ ;IF NEQ, YES 

;REQUEST DATA PATH 
;REQUEST MAP REGISTERS 
;LOAD UNIBUS MAP REGISTERS 
UCB$L_CRB(R5),R1 ;GET CRB ADDRESS 

#VEC$V_DATAPATH,#VEC$S_DATAPATH,- ;EXTRACT DATA-PATH NUMBER 

CRB$L_INTD+VEC$B_DATAPATH(R1),RO ; FOR UBA-RESOURCE FLAG 
RO,UCB$W_DL_DPN(R5) ;INDICATE UBA RESOURCES ALLOCATED 


MOVZWL UCB$W_B0FF(R5),RO ;GET BYTE OFFSET IN PAGE 

INSV CRB$L_INTD+VEC$W_MAPREG(R1),- ;INSERT HIGH 7 BITS OF ADDRESS 

#9,#7,RO ;... 

MOVW RO,UCB$W_DL_SBA(R5) ;SET BUFFER ADDRESS 

EXTZV #7,#2,CRB$L_INTD+VEC$W_MAPREG(R1),RO ;GET MEMORY EXTENSION BITS 
MULB3 #16,RO,UCB$B_DL_XBA(R5) ;POSITION MEMORY EXTENSION BITS TO <5:4> 


COMMON TRANSFER POINT 


; FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT EMPTY THE 
; INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE PREVIOUS READ TO THE 
; USER'S BUFFER. 

5$: BSBW DL_MOVE_TO_BUFFER ;COPY TO USER BUFFER 

; PUT BUFFER ADDRESS, WORD COUNT, AND DISK ADDRESS IN DEVICE REGISTERS 


MOVW UCB$W DL SBACR5),RL BA(R4) ;SET BUFFER ADDRESS 


MNEGW 

UCB$W_BCR(R5),- 
UCB$W_DL_PBCR(R5) 

MOVZBL 

UCB$B_SECT0RS(R5),R2 

MOVZBL 

UCB$W_DA(R5),R1 

SUBW 

R1,R2 

MULW 

#256,R2 

CMPW 

UCB$W_DL_PBCR(R5),R2 

BLEQU 

10$ 

MOVW 

R2.UCB$W_DL_PBCR(R5) 


GET BYTES LEFT TO TRANSFER AND - 
ASSUME ONLY ONE TRANSFER NEEDED 
GET SECTORS/SURFACE 
GET DESIRED SECTOR 
CALCULATE SECTORS LEFT ON SURFACE 
CONVERT TO BYTES LEFT ON SURFACE 
ARE ADDITIONAL TRANSFERS REQUIRED? 
IF LEQU, NO 

SET BYTE COUNT FOR THIS TRANSFER 


E—27 








A Sample Q-Bus Driver 


FOR A WRITE OPERATION WHEN NO ADAPTER MAPPING IS PRESENT 

FILL INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE USER'S BUFFER. 


10$: 

BSBW 

DL_MOVE_FROM_BUFFER 

COPY FROM USER BUFFER 


MOVZBL 

UCB$B_DL_XBA(R5),R0 

SET MEMORY EXTENSION BITS 


BISW 

FTAB[R3],RO 

MERGE XBA BITS WITH FUNCTION 


DIVW3 

#2,UCB$W_DL_PBCR(R5),R2 

CALCULATE TRANSFER WORD COUNT 


MNEGW 

R2,RL_MP(R4) 

SET TRANSFER WORD COUNT 


MOVZBL 

UCB$W_DA(R5),R1 

PUT DESIRED SECTOR IN Rl<5:0> 


INSV 

UCB$W_DA+1(R5),#6,#1,R1 

INSERT DESIRED SURFACE IN Rl<6> 


INSV 

UCB$W_DC(R5),#7,#9.R1 

INSERT DESIRED CYLINDER IN Rl<15:7> 


MOVW 

R1,RL_DA(R4) 

SET DESIRED DISK ADDRESS 

; EXECUTE THE TRANSFER FUNCTION 



CKPWR 


DISABLE INTERRUPTS, CHECK POWER,- 
AND PUT UNIT NUMBER IN R2<9:8> 


BISW3 

R2,RO,RL_CS(R4) 

EXECUTE FUNCTION 


WFIKPCH 

RETREG,#6 

WAITFOR INTERRUPT AND KEEP CHANNEL 
RETURN HERE FROM ISR SAVING REGISTERS 


IOFORK 


CREATE FORK PROCESS (RETURN TO ISR) 
RETURN HERE FROM ISR REI ROUTINE 

; PURGE DATA PATH 



CLRB 

UCB$B_DL_DPPE(R5) 

CLEAR DATA-PATH-PURGE ERROR 


JSB 

G~IOC$PURGDATAP 

PURGE DATA PATH 


BLBS 

RO,20$ 

IF SET, NO PURGE ERRORS 


INCB 

UCB$B_DL_DPPE(R5) 

SET DATA-PATH-PURGE ERROR 

; SAVE 

UBA REGISTERS FOR UPDATE AND REGDUMP ROUTINES 

20$: 

BBC 

#UCB$V_DL_MAPPING,- 

ADAPTER MAPPING? 



UCB$W_DL_FLAGS(R5),30$ 

IF BC, NO 


MOVL 

R1,UCB$L_DL_DPR(R5) 

SAVE DATA-PATH REGISTER 


EXTZV 

#9,#7,UCB$W_DL_BA(R5).RO 

;EXTRACT LOW BITS OF FINAL MAP REG NO 


EXTZV 

#4,#2,UCB$W_DL_CS(R5).R1 

;EXTRACT HI BITS OF FINAL MAP REG NO. 


INSV 

R1,#7,#2,RO 

INSERT HIGH BITS OF FINAL MAP REGISTER 


CMPW 

#495,RO 

LEGAL MAP REGISTER NUMBER? 


BGEQ 

25$ 

IF GEQ, YES 


MOVZWL 

#495,RO 

RESTRICT MAP REGISTER NUMBER 

25$: 

MOVL 

(R2)[RO],UCB$L_DL_FMPR(R5) ;SAVE FINAL MAP REGISTER NUMBER 


CLRL 

UCB$L_DL_PMPR(R5) 

;CLEAR PREVIOUS MAP REGISTER CONTENTS 


DECL 

RO 

;CALCULATE PREVIOUS MAP REGISTER NUMBER 


CMPV 

#VEC$V_MAPREG,#VEC$S_MAPREG,- ;ANY PREVIOUS MAP REGISTER? 

CRB$L_INTD+VEC$W_MAPREG(R3),R0 ;... 


BGTR 

30$ 

;IF GTR, NO 


MOVL 

(R2)[RO],UCB$L_DL_PMPR(R5) ;SAVE PREVIOUS MAP REGISTER 

30$: 

BBC 

#RL_CS_V_CE,UCB$W_DL_CS(R5),40$ ;IF CLR, NO RL ERRORS 


BRW 

RETREG 

DEVICE ERROR 

40$: 

BLBC 

UCB$B_DL_DPPE(R5),45$ 

IF CLR, NO PURGE ERROR 


BRW 

RETREG 

PURGE ERROR 
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RETURN HEADER INFORMATION FOR READ HEADER FUNCTION 


45$: 

CMPB 

#CDF_READHEAD,UCB$B_CEX(R5) ;READ HEADER FUNCTION? 


BNEQ 

DATACHECK 

IF NEQ, NO 


PUSHL 

UCB$W_BCR(R5) 

SAVE NEG BYTES REMAINING 


PUSHL 

UCB$L_SVAPTE(R5) 

SAVE ADDRESS OF PTE 


MOVAB 

UCB$W_DL_DB(R5),R1 

SET ADDRESS OF INTERNAL BUFFER 


MOVL 

#6, R2 

SET NUMBER OF BYTES TO MOVE 


CMPW 

R2,UCB$W_BCNT(R5) 

ROOM FOR FULL HEADER? 


BLSSU 

50$ 

IF LSSU, YES 


MOVZWL 

UCB$W_BCNT(R5),R2 

SET LENGTH OF PARTIAL HEADER 

50$: 

SUBW3 

UCB$W_BCNT(R5),R2,UCB$W_BCR(R5) ;CALCULATE TRANSFER BYTE COUNT 


JSB 

G~IOC$MOVTOUSER 

MOVE HEADER TO USER BUFFER 


POPL 

UCB$L_SVAPTE(R5) 

RESTORE ADDRESS OF PTE 


POPL 

UCB$W_BCR(R5) 

RESTORE NEG BYTES REMAINING 

; PERFORM DATA 

CHECK, IF REQUESTED 


DATACHECK: 


DATACHECK AFTER PARTIAL TRANSFER 


BBC 

#IO$V_DATACHECK,- 
UCB$W_FUNC(R5).UPDATE 

IF CLR, DATA CHECK NOT REQUESTED 


BBSC 

#0,UCB$B_DL_DCHEK(R5) 
UPDATE 

IF SET, DATA CHECK ALREADY PERFORMED 


INCB 

UCB$B_DL_DCHEK(R5) 

SET DATA CHECK IN PROGRESS 


MOVZBL 

#IO$_WRITECHECK,R3 

SET CASE INDEX TO WRITE CHECK 


BRW 

XFER 

BRANCH TO PERFORM WRITE CHECK 

; UPDATE BUFFER 

ADDRESS, CURRENT DISK ADDRESS, AND BYTES REMAINING 

; FOR 

NEXT TRANSFER 


UPDATE 

BBC 

#UCB$V_DL_MAPPING,- 

UPDATE TRANSFER PARAMETERS 

ADAPTER MAPPING? 



UCB$W_DL_FLAGS(R5),10$ 

IF BC, NO 


BICB3 

#~XCF,UCB$W_DL_CS(R5),- 
UCB$B_DL_XBA(R5) 

SAVE MEMORY EXTENSION BITS 


MOVW 

UCB$W_DL_BA(R5),- 
UCB$W_DL_SBA(R5) 

UPDATE SAVED BUFFER ADDRESS 

10$: 

CLRB 

UCB$W_DA(R5) 

UPDATE DESIRED SECTOR TO ZERO 


ADDL3 

#"0100,UCB$W_DL_DA(R5),R1 ;INCREMENT CYLINDER k SURFACE 


EXTZV 

#6,#1,R1,R2 

EXTRACT DESIRED DISK SURFACE 


MOVB 

R2,UCB$W_DA+1(R5) 

UPDATE DESIRED DISK SURFACE 


EXTZV 

#7,#9,R1,R2 

EXTRACT DESIRED DISK CYLINDER 


MOVW 

R2,UCB$W_DC(R5) 

UPDATE DESIRED DISK CYLINDER 


ADDW 

UCB$W_DL_PBCR(R5),- 
UCB$W_BCR(R5) 

UPDATE NEG BYTES REMAINING TO XFER 


BEQL 

RETREG 

IF EQL, TRANSFER COMPLETE 


BRW 

FDISPATCH 

MORE BYTES REMAINING - CONTINUE 
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GET STATUS AND RESET ERRORS 


RETREG: 


;GET STATUS AND RESET ERRORS 


FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT 
EMPTY INTERNAL BUFFER INTO USER'S BUFFER FOR LAST READ 


BSBW DL_MOVE_TO_BUFFER 


MOVE LAST READ INTO USER'S BUFFER 


SETIPL 

MOVW 

CLRL 

INSV 

BISW3 

BSBW 

MOVW 

MOVW 

BISW3 

BSBW 


UCB$B_FIPL(R5) 
#RL_DA_M_STS!- 


MAKE SURE AT FORK IPL (TIMEOUT) 
PUT GET STATUS IN DAR 


RL_DA_M_MRK,RL_DA(R4) ;... 

R2 ;CLEAR R2 FOR UNIT NUMBER 

UCB$W_UNIT(R5),#8,#8,R2 ;GET UNIT NUMBER 

R2,#F_GETSTATUS,RL_CS(R4) ;EXECUTE GET STATUS 

DL.WAIT ;WAIT FOR CONTROLLER 

RL_MP(R4),UCB$W_DL_MP(R5) ;RETRIEVE ERROR REGISTER 
#RL_DA_M_RST!- ;PUT GET STATUS & RESET IN DAR 

RL_DA_M_STS!RL_DA_M_MRK,RL_DA(R4) ;... 

R2,#F_GETSTATUS,RL_CS(R4) ;EXECUTE RESET 

DL.WAIT ;WAIT FOR CONTROLLER 


DETERMINE EXIT - SPECIAL CONDITION, FATAL ERROR, RETRIABLE ERROR, OR SUCCESS 


1 $: 


2 $: 


4$: 


CMPZV 

BEQL 

BICW 

MOVZWL 

BRW 

BITW 

BNEQ 


#0,#5,UCB$W_DL_MP(R5),- ;HEADS. BRUSHES, STATE OK? 
#RL_MP_M_BH!RL_MP_M_HO!RL.SLM ;... 

1$ ;IF EQL, YES, ONLINE 

#UCB$M_TIM0UT,UCB$W_STS(R5) ;CLEAR DEVICE TIME OUT 


#SS$_MEDOFL,RO 

FUNCXT 

#UCB$M_POWER!- 


SET MEDIUM OFFLINE STATUS 
RETURN 

POWER FAIL OR DEVICE TIMEOUT? 


UCB$M_TIMOUT,UCB$W_STS(R5) 


SPECOND 


;IF NEQ, YES, SPECIAL CONDITION 


BBS #RL_MP_V_VC,UCB$W_DL_MP(R5),20$ ;IF SET, VOLUME INVALID 

BBS #RL_CS_V_CE,UCB$W_DL_CS(R5),2$ ;IF SET, RL ERROR 

BLBC UCB$B_DL_DPPE(R5),10$ ;IF CLR, NO PURGE ERROR 

JSB G~ERL$DEVICERR ;ALLOCATE AND FILL ERROR MESSAGE BUFFER 

BBS #I0$V_INHRETRY,UCB$W_FUNC(R5),20$ ;IF SET, RETRY INHIBITED 

BBS #RL_CS_V_NXM,UCB$W_DL_CS(R5),20$ ;IF SET, NONEXISTENT MEMORY 

BBC #RL_CS_V_DE,UCB$W_DL_CS(R5).5$ ;IF CLR, NO DRIVE ERRORS 

BBC #RL_MP_V_WL,UCB$W_DL_MP(R5),4$ ;IF CLR, NOT WRITE LOCKED 

BBS #RL_MP_V_WGE,UCB$W_DL_MP(R5),20$ ;IF WL & WGE SET, WL ERROR 

BITW #RL_MP_M_WDE!- ;WRITE DATA ERROR, OR 

RL_MP_M_CHE!- ;CURRENT HEAD ERROR. OR 

RL_MP_M_WGE!- ;WRITE GATE ERROR, OR 

RL_MP_M_DSE,UCB$W_DL_MP(R5) ;DRIVE SELECT ERROR? 

BNEQ 20$ ;IF NEQ, YES 


RETRIABLE ERROR EXIT 


5$: 


CVTBL @UCB$L_DPC(R5).-(SP) ;GET BRANCH DISPLACEMENT 

ADDL (SP)♦,UCB$L_DPC(R5) ;CALCULATE RETURN ADDRESS - 1 
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SUCCESSFUL OPERATION EXIT 

10$: INCL UCB$L_DPC(R5) 

JMP <3UCB$L_DPC(R5) 

FATAL ERROR EXIT 


;ADJUST TO CORRECT RETURN ADDRESS 
;RETURN TO DRIVER 


20$: BRW FATALERR ;FATAL ERROR EXIT 

SPECIAL CONDITION EXIT (POWER FAILURE OR DEVICE TIMEOUT) 



SPECOND: 

BBS 

JSB 

BICW 

MOVZWL 

DECB 

BEQL 

BRW 

RESETXFR: 

MOVL 

MNEGW 

BRW 

PWRFAIL: 


#UCB$V_POWER,UCB$W_STS(R5),PWRFAIL ;IF SET, POWER FAILURE 

;IF CLR, DEVICE TIMEOUT 
G~ERL$DEVICTMO ;LOG DEVICE TIMEOUT 

#UCB$M_TIMOUT,UCB$W_STS(R5) ;CLEAR TIMEOUT STATUS 


#SS$_TIMEOUT,RO 
UCB$B_ERTCNT(R5) 
RESETXFR 
FDISPATCH 


SET DEVICE TIMEOUT STATUS 
ANY ERROR RETRIES REMAINING? 
IF EQL, NO 
RETURN 

RESET TRANSFER BYTE COUNT 
GET ADDRESS OF I/O PACKET 


UCB$L_IRP(R5),R3 
IRP$W_BCNT(R3),UCB$W_BCR(R5) ;RESET BYTE COUNT 
FUNCXT ;EXIT 


BICW 

TSTW 

BEQL 

BBC 

RELDPR 

RELMPR 

50$: RELCHAN 

MOVL 
MOVQ 

BRW 
.PAGE 
.SBTTL 

++ 

DL$INT - RL11 


#UCB$M_POWER,UCB$W 
UCB$W_DL_DPN(R5) 
50$ 

#UCB$V_DL_MAPPING, 
UCB$W_DL_FLAGS(R5) 


UCB$L_IRP(R5),R3 
IRP$L_SVAPTE(R3) 
UCB$L_SVAPTE(R5) 
PREPROCESS 


;POWER FAILURE 

_STS(R5) ;CLEAR POWER FAILURE BIT 
;ARE UCB RESOURCES ALLOCATED? 
IF EQL, NO 
;ADAPTER MAPPING? 

50$ ;IF BC, NO 

;RELEASE DATA PATH 
RELEASE MAP REGISTERS 
RELEASE CHANNEL IF OWNED 
GET ADDRESS OF I/O PACKET 
RESTORE TRANSFER PARAMETERS 


RETURN TO PREPROCESS UCB FIELDS 


INTERRUPT SERVICE ROUTINE 
INTERRUPT SERVICE ROUTINE 


FUNCTIONAL DESCRIPTION: 

THIS ROUTINE IS ENTERED VIA A JSB INSTRUCTION WHEN AN INTERRUPT 
OCCURS ON AN RL11 DISK CONTROLLER. IF THE INTERRUPT IS NOT EXPECTED, 
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THE UNSOLICITED INTERRUPT ROUTINE DISMISSES THE INTERRUPT. IF 
THE INTERRUPT IS EXPECTED, DEVICE REGISTERS ARE SAVED AND THE 
DRIVER IS CALLED AT ITS INTERRUPT RETURN ADDRESS. THE DRIVER FORKS, 
CAUSING A RETURN TO THIS ROUTINE, WHICH RESTORES GENERAL REGISTERS 
AND DISMISSES THE INTERRUPT. 

INPUTS: 

00(SP) - POINTER TO ADDRESS OF THE IDB 

04(SP) - SAVED RO 

08(SP) - SAVED R1 

12(SP) - SAVED R2 

16(SP) - SAVED R3 

20(SP) - SAVED R4 

24(SP) - SAVED R5 

28(SP) - PC AT THE TIME OF THE INTERRUPT 
32(SP) - PSL AT THE TIME OF THE INTERRUPT 

OUTPUTS: 

DEVICE REGISTERS ARE SAVED, IPL IS LOWERED TO FORK LEVEL, THE 
INTERRUPT IS DISMISSED, ALL REGISTERS EXCEPT R0-R5 ARE PRESERVED. 


DL.INT:: 

MOVL 

MOVQ 

TSTL 

BEQL 

BBCC 


CMPB 

BNEQ 

MOVW 

MOVW 

MOVW 


@(SP)+,R3 
(R3),R4 
R5 

DL.UNSOLNT 
#UCB$V_INT,- 

UCB$W_STS(R5),DL_UNSOLNT 


INTERRUPT SERVICE ROUTINE 

REMOVE ADDRESS OF IDB FROM STACK 

GET ADDRESS OF CSR AND UCB 

IS R5 A ZERO 

IF EQL, NO OWNER 

IF CLR, INTERRUPT NOT EXPECTED 


#CDF_READHEAD,UCB$B_CEX(R5) ;READ HEADER FUNCTION? 

10$ ;IF NEQ, NO 

RL_MP(R4),UCB$W_DL_DB(R5) ;SAVE SECTOR HEADER INFORMATION 
RL_MP(R4),UCB$W_DL_DB+2(R5) ;... 

RL_MP(R4),UCB$W_DL_DB+4(R5) ;... 


10 $: 


MOVAB RL_CS(R4),R2 

MOVAB UCB$W_DL_CS(R5).R3 

MOVW (R2) + , (R3) + 

MOVW (R2)+,(R3)+ 

MOVW (R2) + , (R3) + 

MOVW (R2)+,(R3)+ 


GET ADDRESS OF CONTROL STATUS REGISTER 
GET ADDRESS OF REGISTER SAVE AREA 
SAVE CONTROL STATUS REGISTER 
SAVE BUFFER ADDRESS REGISTER 
SAVE DISK ADDRESS REGISTER 
SAVE MULTIPURPOSE REGISTER 


20 $: 


MOVQ UCB$L_FR3(R5),R3 

JSB <3UCB$L_FPC(R5) 


RESTORE DRIVER CONTEXT 

CALL DRIVER AT INTERRUPT RETURN ADDRESS 


DL.UNSOLNT: 

POPR 
RE I 


#~M<R0,R1,R2,R3,R4,R5> 


UNSOLICITED INTERRUPT 
RESTORE R0-R5 
RETURN FROM INTERRUPT 
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.PAGE 

.SBTTL REGISTER DUMP ROUTINE 


++ 

DL_REGDUMP - REGISTER DUMP ROUTINE 
FUNCTIONAL DESCRIPTION: 

THIS ROUTINE IS CALLED TO SAVE THE DEVICE REGISTERS AND UBA RESOURCE 
REGISTERS IN A SPECIFIED BUFFER. IT IS CALLED FROM THE DEVICE ERROR 
LOGGING ROUTINE AND FROM THE DIAGNOSTIC BUFFER FILL ROUTINE. 

INPUTS: 

RO - ADDRESS OF REGISTER SAVE BUFFER 

R4 - ADDRESS OF DEVICE CONTROL STATUS REGISTER (CSR) 

R5 - ADDRESS OF UNIT-CONTROL BLOCK (UCB) 

OUTPUTS: 


THE DEVICE AND UBA REGISTERS ARE SAVED IN THE SPECIFIED BUFFER. 

RO CONTAINS THE ADDRESS OF THE NEXT EMPTY LONGWORD IN THE BUFFER. 
ALL REGISTERS EXCEPT R1 AND R2 ARE PRESERVED. 



DL_REGDUMP: 


10 $: 


MOVL 

#<RL_NUM_REGS+5>,(RO)+ 

MOVAL 

UCB$W_DL_CS(R5),R1 

MOVZBL 

#RL_NUM_REGS,R2 

MOVZWL 

(Rl) + , (RO) + 

SOBGTR 

R2,10$ 

MOVZWL 

(Rl) + , (RO) + 

MOVL 

(Rl)+,(RO)+ 

MOVL 

(Rl) + , (RO) + 

MOVL 

(Rl) + , (RO) + 

MOVZBL 

RSB 

(Rl)+,(R0)+ 

.PAGE 

.SBTTL 

MOVE TO USER BUFFER ROl 


REGISTER DUMP ROUTINE 

INSERT NUMBER OF REGISTERS 

GET ADDRESS OF SAVED DEVICE REGISTERS 

GET NUMBER OF DEVICE REGISTERS TO MOVE 

DUMP REGISTER IN BUFFER 

IF GTR, STILL MORE TO MOVE 

DUMP DATA-PATH NUMBER 

DUMP DATA-PATH REGISTER 

DUMP FINAL MAP REGISTER 

DUMP PREVIOUS MAP REGISTER 

DUMP DATA-PATH-PURGE-ERROR REGISTER 

RETURN 


++ 

DL_MOVE_TO_BUFFER - MOVE TO USER BUFFER 
FUNCTIONAL DESCRIPTION: 

THIS ROUTINE MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND 
THE USER'S BUFFER. 


INPUTS: 

R5 - UCB ADDRESS 
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OUTPUTS: 


DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND THE USER'S BUFFER. 
REGISTER'S RO.Rl, AND R2 ARE DESTROYED 


DL_MOVE_TO_BUFFER: 


BUFFER MOVE ROUTINE 



BBS 

#UCB$V_DL_MAPPING,- 

ADAPTER MAPPING? 



UCB$W_DL_FLAGS(R5),10$ 

IF BS, YES, NOTHING TO MOVE 


CMPB 

#CDF_READDATA,UCB$B_CEX(R5);READ DATA OPERATION? 


BNEQ 

10$ 

IF NEQ, NOT A READ 


BBS 

#0,UCB$B_DL_DCHEK(R5),- 

DATA CHECK IN PROGRESS? 



10$ 

IF BS, YES, NOTHING TO MOVE 


TSTL 

UCB$A_DL_MOVRTN(R5) 

ANYTHING TO MOVE? 


BEQL 

20$ 

IF EQL, NO 


MOVL 

UCB$L_DL_BUFADR(R5),R0 

GET USER BUFFER POINTER 


MOVL 

UCB$A_DL_BUF_VA(R5),R1 

GET PHYSICALLY CONTIGUOUS BUFFER 


MOVZWL 

UCB$W_DL_PBCR(R5),R2 

GET NUMBER OF BYTES TO TRANSFER 


JSB 

<3UCB$A_DL_M0VRTN (R5) 

CALL MOVE ROUTINE 


MOVL 

RO,UCB$L_DL_BUFADR(R5) 

SAVE INTERNAL BUFFER POINTER 


MOVAB 

G~I0C$M0VT0USER2,- 
UCB$A_DL_MOVRTN(R5) 

SET NEXT MOVE ROUTINE TO BE USED 

10$: 

RSB 


RETURN 

20$: 

MOVAB 

G~IOC$MOVTOUSER,- 
UCB$A_DL_MOVRTN(R5) 

SET NEXT MOVE ROUTINE TO BE USED 


RSB 


RETURN 


.PAGE 



; +♦ 

.SBTTL 

MOVE FROM USER BUFFER ROUTINE 

; DL_MOVE_FROM_ 

.BUFFER - MOVE FROM USER BUFFER 

; FUNCTIONAL DESCRIPTION: 


; THIS 

ROUTINE 

MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND 


THE USER'S BUFFER. 
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INPUTS: 

R5 - UCB ADDRESS 
OUTPUTS: 

DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND THE USER'S BUFFER. 
REGISTER'S RO.R1. AND R2 ARE DESTROYED 


DL_MOVE_FROM_BUFFER: ;BUFFER MOVE ROUTINE 

BBS #UCB$V_DL_MAPPING,- ;ADAPTER MAPPING? 

UCB$W_DL_FLAGS(R5),10$ ;IF BS, YES, NOTHING TO MOVE 

CMPB #CDF_WRITEDATA,UCB$B_CEX(R5);WRITE DATA OPERATION? 


BNEQ 

10$ 

BBS 

#0.UCB$B_DL_DCHEK(R5),- 

MOVL 

10$ 

UCB$L_DL_BUFADR(R5),R0 

MOVL 

UCB$A_DL_BUF_VA(R5),R1 

MOVZWL 

UCB$W_DL_PBCR(R5),R2 

JSB 

<3UCB$A_DL_M0VRTN (R5) 

MOVL 

RO,UCB$L_DL_BUFADR(R5) 

MOVAB 

G~I0C$M0VFRUSER2,- 

RSB 

UCB$A_DL_MOVRTN(R5) 


DL.END: 


IF NEQ, NOT A WRITE 
DATA CHECK IN PROGRESS? 

IF BS, YES, NOTHING TO MOVE 

GET USER BUFFER POINTER 

GET PHYSICALLY CONTIGUOUS BUFFER ADDRESS 

GET NUMBER OF BYTES TO TRANSFER 

CALL MOVE ROUTINE 

SAVE INTERNAL BUFFER POINTER 

SET NEXT MOVE ROUTINE TO BE USED 

RETURN 

ADDRESS OF LAST LOCATION IN DRIVER 


.END 
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Devices 


.TITLE XADRIVER - VAX/VMS DR11-W DRIVER 
.IDENT 'V03-006' 



**************************************************************************** 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 

ALL RIGHTS RESERVED. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 


**************************************************************************** 
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+♦ 

FACILITY: 

VAX/VMS Executive, I/O Drivers 
ABSTRACT: 

This module contains the DR11-W driver: 

Tables for loading and dispatching 
Controller-initialization routine 
FDT routine 
Start-I/0 routine 
Interrupt-servicing routine 
Device-specific cancel-I/0 routine 
Error-logging, register-dumping routine 


ENVIRONMENT: 

Kernal mode, nonpaged 
AUTHOR: 

C. A. Programmer 10-JAN-79 


MODIFIED BY: 

V03-006 TMK0001 T. M. Programmer 07-Dec-1983 

Fix a broken branch. 

V03-005 JLV0304 J. V. Programmer 24-AUG-1983 

Several bug fixes. All word writes to XA_CSR now have 
ATTN set so as to prevent lost interrupts. Attention 
AST list is synchronized at device IPL in DEL_ATTNAST. 
Correct status is returned on a set mode ast that 
is returns through EXE$FINISHIO. REQCOM's are always 
done at FIPL. Signed division that prevented full size 
transfers has been fixed. 


V03-004 KDM0059 K. D. Programmer 14-Jul-1983 

Change time-wait loops to use new TIMEDWAIT macro. 
Add $DEVDEF. 

V03-003 KDM0002 K. D. Programmer 28-Jun-1982 

Added $DYNDEF, $DCDEF, and $SSDEF. 

.SBTTL External and local symbol definitions 
; External symbols 

$ACBDEF ; AST control block 

$CRBDEF ; Channel request block 

$DCDEF ; Device types 
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SDDBDEF 

$DEVDEF 

$DPTDEF 

$DYNDEF 

$EMBDEF 

SIDBDEF 

SIODEF 

$IPLDEF 

$IRPDEF 

$PRDEF 

SPRIDEF 

$SSDEF 

$UCBDEF 

SVECDEF 

$XADEF 


Device data block 

Device characteristics 

Driver prolog table 

Dynamic data structure types 

EMB offsets 

Interrupt data block 

I/O function codes 

Hardware IPL definitions 

I/O request packet 

Internal processor registers 

Scheduler priority increments 

System status codes 

Unit control block 

Interrupt vector block 

Define device specific characteristics 


; Local symbols 

; Argument list (AP) offsets for device-dependent QIO parameters 


PI 

= 

0 

P2 

= 

4 

P3 

= 

8 

P4 

= 

12 

P5 

= 

16 

P6 

= 

20 


; Other constants 


DEF_TIMEOUT 

DEF.BUFSIZ 

RESET.DELAY 


10 

65535 

«2+9>/10> 


First QIO parameter 
Second QIO parameter 
Third QIO parameter 
Fourth QIO parameter 
Fifth QIO parameter 
Sixth QIO parameter 


10 second default device timeout 
Default buffer size 
Delay N microseconds after RESET 
(rounded up to 10 microsec intervals) 


; DR11-W definitions that follow the standard UCB fields 
; *** NOTE *** ORDER OF THESE UCB FIELDS IS ASSUMED 



SDEFINI UCB 
.=UCB$L_DPC+4 



$DEF 

UCB$L_XA_ATTN 

.BLKL 1 

; Attention 

AST listhead 

$DEF 

UCB$W_XA_CSRTMP 

.BLKW 1 

; Temporary 

storage of CSR image 
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$DEF 

UCB$W_XA_BARTMP 

.BLKW 1 


; Temporary storage of BAR image 

$DEF 

UCB$W_XA_CSR 

.BLKW 1 


; Saved CSR on interrupt 

$DEF 

UCB$W_XA_EIR 

.BLKW 1 


; Saved EIR on interrupt 

$DEF 

UCB$W_XA_IDR 

.BLKW 1 


; Saved IDR on interrupt 

$DEF 

UCB$W_XA_BAR 

.BLKW 1 


; Saved BAR register on interrupt 

$DEF 

UCB$W_XA_WCR 

.BLKW 1 


; Saved WCR register on interrupt 

$DEF 

UCB$W_XA_ERROR 

.BLKW 1 


; Saved device status flag 

$DEF 

UCB$L_XA_DPR 

.BLKL 1 


; Data-path register's contents 

$DEF 

UCB$L_XA_FMPR 

.BLKL 1 


; Final map register's contents 

$DEF 

UCB$L_XA_PMPR 

.BLKL 1 


; Previous map register's contents 

$DEF 

UCB$W_XA_DPRN 

.BLKW 1 


; Saved data-path register's number 
; And data-path-parity-error flag 

; Bit 

UCB$K_ 

positions for device-dependent 

$VIELD UCB,0,<- 

<ATTNAST,,M>,- 
<UNEXPT,, M>, - 
> 

_SIZE=. 

SDEFEND UCB 

status field in UCB 

; UCB device-specific bit definitions 
; ATTN AST requested 
; Unexpected interrupt received 

; Device register offsets from 

$DEFINI XA 

CSR address 

; Start of DR11-W definitions 

$DEF 

XA.WCR 

.BLKW 

1 

; Word count 

$DEF 

XA.BAR 

.BLKW 

1 

; Buffer address 

$DEF 

XA.CSR 


; Control/status 


; Bit positions for device control/status register 

SEQULST XA$K_,,0,1,<- ; Define CSR FNCT bit values 

<FNCT1,2>- 
<FNCT2,4>- 
<FNCT3,8>- 

<STATUSA,2048>- ; Define CSR STATUS bit values 

<STATUSB,1024>- 
<STATUSC,512>- 

> 
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$VIELD XA_CSR,0,<- 
<G0,,M>,- 
<FNCT,3,M>,- 
<XBA,2,M>,- 
<IE,,M>,- 
<RDY,,M>,- 
<CYCLE,,M>,- 
<STATUS,3,M>,- 
<MAINT,,M>,- 
<ATTN,,M>,- 
<NEX,,M>,- 
<ERROR,, M>, - 

> 

$DEF XA_EIR 


; Control/status register 
; Start device 
; CSR FNCT bits 
; Extended address bits 
; Enable interrupts 
; Device ready for command 
; Starts slave transmit 
; CSR STATUS bits 
; Maintenance bit 
; Status from other processor 
; Nonexistent memory flag 
; Error or external interrupt 

; Error information register 


; Bit positions for error information register 


SVIELD XA_EIR,0,<- 

<REGFLG..M>,- 
<SPARE,7,M>,- 
<BURST,,M>, - 
<DLT,,M>,- 
<PAR,, M>, - 
<ACLO,,M>,- 
<MULTI, ,M> ,- 
<ATTN,.M>.- 
<NEX,,M>, - 
<ERROR,,M>,- 

> 

.BLKW 1 

$DEF XA_IDR 
$DEF XA_ODR 

.BLKW 1 
SDEFEND XA 


Error information register 

Flags whether EIR or CSR is accessed 

Unused - spare 

Burst mode transfer occured 

timeout for successive burst transfer 

Parity error during DATI/P 

Power fail on this processor 

Multicycle request error 

ATTN - same as in CSR 

NEX - same as in CSR 

ERROR - same as in CSR 


Input-data-buffer register 
Output-data-buffer register 

End of DR11-W definitions 


.SBTTL Device Driver Tables 


Driver prologue table 
DPTAB 


END=XA_END,- 
ADAPTER=UBA,- 
FLAGS=DPT$M_SVP,- 
UCBSIZE=UCB$K_SIZE,- 
NAME=XADRIVER 


DPT.STORE INIT 


DPT.STORE UCB,UCB$B_FIPL,B,8 
DPT_STORE UCB,UCB$B_DIPL,B,22 
DPT.STORE UCB,UCB$L_DEVCHAR,L,<- 
DEV$M_RTM!- 
DEV$M_ELG!- 
DEV$M_IDV!- 
DEV$M_ODV> 

DPT.STORE UCB,UCB$B_DEVCLASS.B,DC$_REALTIME 
DPT.STORE UCB,UCB$B_DEVTYPE,B,DT$_DR11W ; Device 
DPT_STORE UCB,UCB$W_DEVBUFSIZ, W, - 
XA_DEF_BUFSIZ 


DPT-creation macro 
End of driver label 
Adapter type 

Allocate system page table 
UCB size 
Driver name 
Start of load 
initialization table 
Device fork IPL 
Device interrupt IPL 
Device characteristics 
Real-time device 
Error Logging enabled 
input device 
output device 

; Device class 
Type 

Default buffer size 
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DPT.STORE REINIT 

DPT.STORE DDB,DDB$L_DDT,D,XA$DDT 
DPT.STORE CRB, CRB$L_INTD+4 , D, - 
XA_INTERRUPT 

DPT.STORE CRB.CRB$L_INTD+VEC$L_INITIAL,- 
D,XA_CONTROL_INIT 
DPT.STORE END 


Start of reload 
initialization table 
Address of DDT 
Address of interrupt 
service routine 
Address of controller 
initialization routine 
End of initialization 
tables 


; Driver dispatch table 


DDTAB 


DEVNAM=XA,- 
START=XA_START,- 
FUNCTB=XA_FUNCTABLE,- 
CANCEL=XA_CANCEL,- 
REGDMP=XA_REGDUMP,- 
DIAGBF=«13*4>+«3+5+l>*4», - 
ERLGBF=«13*4>+<1*4>+<EMB$L_DV. 


; DDT-creation macro 
; Name of device 
; Start I/O routine 
; FDT address 
; Cancel I/O routine 
; Register dump routine 
; Diagnostic buffer size 
REGSAV» ; Error log buffer size 


Function dispatch table 


XA.FUNCTABLE: 

FUNCTAB 


FUNCTAB 

FUNCTAB 

FUNCTAB 

FUNCTAB 

FUNCTAB 

FUNCTAB 


; FDT for driver 

, - ; Valid I/O functions 

<READPBLK,READLBLK,READVBLK,WRITEPBLK,WRITELBLK,WRITEVBLK,- 
SETMODE,SETCHAR,SENSEMODE,SENSECHAR> 

, ; No buffered functions 

XA_READ_WRITE,- ; Device-specific FDT 

<READPBLK,READLBLK,READVBLK,WRITEPBLK,WRITELBLK,WRITEVBLK> 

+EXE$READ,<READPBLK,READLBLK,READVBLK> 

+EXE$WRITE, <WRITEPBLK, WRITELBLK, WRITEVBLK> 

XA.SETMODE,<SETMODE,SETCHAR> 

+EXESSENSEMODE,<SENSEMODE.SENSECHAR> 


.SBTTL XA_CONTROL.INIT, Controller initialization 


++ 

XA_CONTROL_INIT, Called when driver is loaded, system is booted, or 
power failure recovery. 

Functional Description: 

1) Allocates the direct data path permanently 

2) Assigns the controller data channel permanently 
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3) Clears the Control and Status Register 

4) If power recovery, requests device timeout 

Inputs: 

R4 = address of CSR 
R5 = address of IDB 
R6 = address of DDB 
R8 = address of CRB 

Outputs: 

VEC$V_PATHLOCK bit set in CRB$L_INTD+VEC$B_DATAPATH 
UCB address placed into IDB$L_OWNER 


XA_CONTROL_INIT: 

MOVL IDB$L_UCBLST(R5),R0 ; Address of UCB 

MOVL RO,IDB$L_0WNER(R5) ; Make permanent controller owner 

BISW #UCB$M_ONLINE.UCB$W_STS(RO) 

; Set device status "on-line" 

; If powerfail has occured and device was active, force device timeout. 

; The user can set his own timeout interval for each request. Time 
; out is forced so a very long timeout period will be short circuited. 

BBS #UCB$V_POWER,UCB$W_STS(RO),10$ 

; Branch if powerfail 
BISB #VEC$M_PATHLOCK,CRB$L_INTD+VEC$B_DATAPATH(R8) 

; Permanently allocate direct datapath 

10 $: 

BSBW XAJDEV.RESET ; Reset DR11W 

RSB ; Done 

.SBTTL XA_READ_WRITE, FDT for device data transfers 

; ++ 

; XA_READ_WRITE, FDT for READLBLK,READVBLK,READPBLK,WRITELBLK,WRITEVBLK, 

; WRITEPBLK 


Functional description: 


1 ) 

2 ) 


Rejects QUEUE I/O's with odd transfer count 

Rejects QUEUE I/O's for BLOCK MODE request to UBA direct data 
path on odd byte boundary 
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3) Stores 

4) Stores 

5) Stores 

6) Checks 


request timeout count specified in P3 into IRP 
FNCT bits specified in P4 into IRP 
word to write into ODR from P5 into IRP 
block mode transfers for memory modify access 


Input8: 


R3 

R4 

R5 

R6 

R8 

AP 


Address of IRP 
Address of PCB 
Address of UCB 
Address of CCB 
Address of FDT routine 
Address of PI 

PI = Buffer address 

P2 = Buffer size in bytes 

P3 = Request timeout period (conditional on IO$M_TIMED) 

P4 = Value for CSR FNCT bits (conditional on IO$M_SETFNCT) 
P5 = Value for ODR (conditional on IO$M_SETFNCT) 

P6 = Address of diagnostic buffer 


Outputs: 

RO = Error status if odd transfer count 
IRP$L_MEDIA = timeout count for this request 
IRP$L_SEGVBN = FNCT bits for DR11-W CSR and ODR image 


XA_READ_ 

.WRITE: 




BLBC 

P2(AP),10$ 

Branch if transfer count even 

2$: 

MOVZWL 

#SS$_BADPARAM,RO 

Set error status code 

5$: 

JMP 

G~EXE$ABORT10 

Abort request 

10$: 

MOVZWL 

IRP$W_FUNC(R3),R1 

Fetch I/O Function code 


MOVL 

P3(AP),IRP$L_MEDIA(R3) 

Set request specific timeout count 


BBS 

#I0$V_TIMED,R1,15$ 

Branch if timeout specified 


MOVL 

#XA_DEF_TIMEOUT,IRP$L_MEDIA(R3) 




; Else set default timeout value 

15$: 

BBC 

#I0$V_DIAGN0STIC,R1,20$ ; 

; Branch if not maintenance reqeust 


EXTZV 

#I0$V_FC0DE,#I0$S_FC0DE,R1,R1 ; AND out all function modifiers 


CMPB 

#IO$_READPBLK,R1 

; If maintenance function, must be 
; physical I/O read or write 


BEQL 

20$ 



CMPB 

#IO$_WRITEPBLK,R1 



BEQL 

20$ 



MOVZWL 

#SS$_N0PRIV,RO 

No privilege for operation 


BRB 

5$ 

Abort request 

20$: 

EXTZV 

#0 , #3 , P4 (AP) , RO 

Get value for FNCT bits 


ASHL 

#XA_CSR$V_FNCT,RO,IRP$L_SEGVBN(R3) ; Shift into position for CSR 


MOVW 

P5(AP),IRP$L_SEGVBN+2(R3) ; Store ODR value for later 


; If this is a block mode transfer, check buffer for modify access 
; whether or not the function is read or write. The DR11-W does 
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not decide whether to read or write, the users device does. 
For word mode requests, return to read check or write check. 


If this is a BLOCK MODE request and the UBA direct data path is 
in use, check the data buffer address for word alignment. If buffer 
is not word aligned, reject the request. 



BBS 


BBS 


BLBS 

25$: 

JMP 

30$: 

RSB 


.SBTTL 

; + + 



#I0$V_W0RD,IRP$W_FUNC(R3),30$ 

; Branch if word mode transfer 
#XA$V_DATAPATH,UCB$L_DEVDEPEND(R5),25$ 

; Branch if Buffered Data Path in use 
P1(AP),2$ ; DDP, branch on bad alignment 

G~EXE$MODIFY ; Check buffer for modify access 

; Return 

XA_SETMODE, Set Mode, Set characteristics FDT 


XA.SETMODE, FDT routine to process SET MODE and SET CHARACTERISTICS 


Functional description: 

If IO$M_ATTNAST modifier is set, queue attention AST for device 
If IO$M_DATAPATH modifier is set, queue packet. 

Else, finish I/O. 


Inputs: 


R3 

R4 

R5 

R6 

R7 

AP 


I/O packet address 
PCB address 
UCB address 
CCB address 
Function code 

QIO parameter list address 


Outputs: 

If IO$M_ATTNAST is specified, queue AST on UCB attention AST list. 
If I0$M_DATAPATH is specified, queue packet to driver. 

Else, use exec routine to update device characteristics 


XA.SETMODE: 

MOVZWL 

BBC 



IRP$W_FUNC(R3),RO 
#IO$V_ATTNAST,RO,20$ 


Get entire function code 
Branch if not an ATTN AST 
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; Attention AST request 



PUSHR 

#~M<R4,R7> 



MOVAB 

UCB$L_XA_ATTN(R5),R7 ; 

Address of ATTN AST control block list 


JSB 

G ~COM$SETATTNAST ; 

Set up attention AST 


POPR 

#~M<R4,R7> 



BLBC 

RO,50$ ; 

Branch if error 


BISW 

#UCB$M_ATTNAST,UCB$W_DEVSTS(R5) 



; 

Flag ATTN AST expected. 


BBC 

#UCB$V_UNEXPT,UCB$W_DEVSTS(R5),10$ 



; 

Deliver AST if unsolicited interrupt 


BSBW 

DEL.ATTNAST 


10$: 

MOVZBL 

#SS$_N0RMAL,RO ; 

Set status 


JMP 

G~EXE$FINISHIOC ; 

That's all for now (clears Rl) 

; If modifier IO$M_DATAPATH is set, 


; queue packet 

The data path is changed 

at driver level to preserve 

; order 

with other requests. 


20$: 

BBS 

S' , #IO$V_DATAPATH, RO, 30$ ; 

If BDP modifier set, queue packet 


JMP 

G~EXE$SETCHAR ; 

Set device characteristics 

; This 

is a request to change data path usage, queue packet 

30$: 

CMPL 

#IO$_SETCHAR,R7 ; 

Set characteristics? 


BNEQ 

45$ ; 

No, must have the privilege 


JMP 

G~EXE$SETMODE ; 

Queue packet to start I/O 

; Error, abort 

10 


45$: 

MOVZWL 

#SS$_N0PRIV,RO ; 

No privilege for operation 

50$: 

CLRL 

R1 



JMP 

G~EXE$ABORT10 ; 

Abort 10 on error 


.SBTTL XA.START, Start I/O routines 

++ 

XA_START - Start a data transfer, set characteristics, enable ATTN AST. 


Functional Description: 

This routine has two major functions: 
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1) Start an I/O transfer. This transfer can be in either word 
or block mode. The FNCTN bits in the DR11-W CSR are set. If 
the transfer count is zero, the STATUS bits in the DR11-W CSR 
are read and the request completed. 

2) Set characteristics. If the function is change data path, the 
new data path flag is set in the UCB. 

Inputs: 

R3 = Address of the I/O request packet 

R5 = Address of the UCB 

Outputs: 

RO = final status and number of bytes transferred 

R1 = value of CSR STATUS bits and value of input data buffer register 

Device errors are logged 

Diagnostic buffer is filled 


.ENABL LSB 
XA.START: 

; Retrieve the address of the device CSR 
ASSUME IDB$L_CSR EQ 0 

MOVL UCB$L_CRB(R5),R4 ; Address of CRB 

MOVL @CRB$L_INTD+VEC$L_IDB(R4),R4 

; Address of CSR 

; Fetch the I/O function code 

MOVZWL IRP$W_FUNC(R3),R1 ; Get entire function code 

MOVW R1,UCB$W_FUNC(R5) ; Save FUNC in UCB for Error Logging 

EXTZV #I0$V_FC0DE,#I0$S_FC0DE,R1,R2 ; Extract function field 

; Dispatch on function code. If this is SET CHARACTERISTICS, we will 
; select a data path for future use. 

; If this is a transfer function, it will either be processed in word 
; or block mode. 

CMPB #IO$_SETCHAR,R2 ; Set characteristics? 

BNEQ 3$ 

; ++ 

; SET CHARACTERISTICS - Process Set Characteristics QIO function 
; INPUTS: 

; XA_DATAPATH bit in Device Characteristics specifies which data path 

; to use. If bit is a one, use buffered data path. If zero, use 

; direct data path. 
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; OUTPUTS: 

; CRB is flagged as to which data path to use. 

; DEVDEPEND bits in device characteristics is updated 

; XA_DATAPATH = 1 -> buffered data path in use 

; XA_DATAPATH = 0 -> direct data path in use 

MOVL UCB$L_CRB(R5),R0 ; Get CRB address 

MOVQ IRP$L_MEDIA(R3),UCB$B_DEVCLASS(R5) ; Set device characteristics 

BISB #VEC$M_PATHLOCK,CRB$L_INTD+VEC$B_DATAPATH(RO) 

; Assume direct data path 

BBC #XA$V_DATAPATH,UCB$L_DEVDEPEND(R5),2$ ; Were we right? 

BICB #VEC$M_PATHLOCK,CRB$L_INTD+VEC$B_DATAPATH(RO) ; Set buffered data path 

2 $: 

CLRL R1 ; Return Success 

MOVZWL #SS$_NORMAL,RO 

REQCOM 

; If subfunction modifier for device reset is set, do one here 

3$: BBC S~#IO$V_RESET,R1,4$ ; Branch if not device reset 

BSBW XA_DEV_RESET ; Reset DR11-W 


This must be a data transfer function (read or write). 
Check to see if this is a zero-length transfer. 

If so, only set CSR FNCT bits and return STATUS from CSR 


4$: 

TSTW 

UCB$W_BCNT(R5) 

Is transfer count zero? 


BNEQ 

10$ 

No, continue with data transfer 


BBC 

DSBINT 

S~#IO$V_SETFNCT,R1.6$ 

Set CSR FNCT specified? 


MOVW 

IRP$L_SEGVBN+2(R3),XA_0DR(R4) 




; Store word in ODR 


MOVZWL 

XA_CSR(R4),RO 



BICW 

#<XA_CSR$M_FNCT!XA_CSR$M_ERROR>,RO 


BISW 

IRP$L_SEGVBN(R3),R0 



BISW 

#XA_CSR$M_ATTN,RO 

; Force ATTN on to prevent lost interrupt 


MOVW 

RO,XA_CSR(R4) 



BBC 

#XA$V_LINK,UCB$L_DEVDEPEND(R5),5$ ; Link mode? 


BICW3 

#XA$K_FNCT2,RO,XA_CSR(R4) ; Make FNCT bit 2 a pulse 

5$: 

ENBINT 



6$: 

BSBW 

XA.REGISTER 

Fetch DR11-W registers 


BLBS 

RO, 7$ 

If error, then log it 


JSB 

G~ERL$DEVICERR 

Log a device error 

7$: 

JSB 

G~IOC$DIAGBUFILL 

Fill diagnostic buffer if specified 


MOVL 

UCB$W_XA_CSR(R5),R1 

Return CSR and EIR in R1 


MOVZWL 

UCB$W_XA_ERR0R(R5),R0 

Return status in RO 


BISB 

#XA_CSR$M_IE,XA_CSR(R4) 

Enable device interrupts 


REQCOM 


Request done 
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; Build CSR image in RO for later use in starting transfers 
10 $: 

MOVZWL UCB$W_BCNT(R5),R0 ; Fetch byte count 

DIVL3 #2,RO,UCB$L_XA_DPR(R5) ; Make byte count into word count 

Set up UCB$W_CSRTMP used for loading CSR later. 



MOVZWL 

XA_CSR(R4),RO 



BICW 

#~C<XA_CSR$M_FNCT>,RO 



BISW 

#XA_CSR$M_IE!XA_CSR$M_ATTN,RO ; Set Interrupt Enable and ATTN 


BBC 

S~#IO$V_SETFNCT,R1,20$ ; 

Set FNCT bits in CSR? 


BICW 

#<XA_CSR$M_FNCT>,RO ; 

Yes, Clear previous FNCT bits 


BISB 

IRP$L_SEGVBN(R3),R0 ; 

OR in new value 

20$: 

BBC 

S~#I0$V_DIAGNOSTIC,R1,23$ 

; Check for maintenance function 


BISW 

#XA_CSR$M_MAINT,RO ; 

Set maintenance bit in CSR image 

; Is 

this a word mode or block mode request? 

23$: 

MOVW 

RO,UCB$W_XA_CSRTMP(R5) ; 

Save CSR image in UCB 


BBC 

S~#I0$V_W0RD,R1,BL0CK_M0DE ; Check if word or block mode 


BRW 

WORD.MODE ; 

Branch to handle word mode 



BLOCK MODE-Process a block-mode (DMA) transfer request 

Functional Description: 

This routine takes the buffer-address, buffer-size, function-code, 
and function-modifier fields from the IRP. It calculates the UNIBUS 
address, allocates the UBA map registers, loads the DR11-W device 
registers, and starts the request. 


Set up UBA 
Start transfer 


BLOCK.MODE: 


; If I0$M_CYCLE subfunction is specified, set CYCLE bit in CSR image. 

BBC #I0$V_CYCLE,R1,25$ ; Set CYCLE bit in CSR? 

BISW #XA_CSR$M_CYCLE,UCB$W_XA_CSRTMP(R5) ; If yes, or into CSR image 


; Allocate UBA data path and map registers 


25$: 



REQDPR 

REQMPR 

LOADUBA 


Request UBA data path 
Request UBA map registers 
Load UBA map reqisters 
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; Calculate the UNIBUS transfer address for the DR11-W from the UBA 
; map register address and byte offset. 


MOVZWL 

MOVL 

INSV 

EXTZV 

ASHL 

BISW 

BISW 

BICW3 

BICW3 

MOVW 


UCB$W_B0FF(R5),R1 ; Byte offset in first page of transfer 

UCB$L_CRB(R5),R2 ; Address of CRB 

CRB$L_INTD+VEC$W_MAPREG(R2),#9,#9,R1 


#16,#2,R1,R2 
#XA_CSR$V_XBA,R2,R2 
#XA_CSR$M_GO,R2 
R2,UCB$W_XA_CSRTMP(R5) 


Insert page number 

Extract bits 17:16 of bus address 

Shift extended memeroy bits for CSR 

Set GO bit into CSR image 

Set into CSR image we are building 


#<XA_CSR$M_GO!XA_CSR$M_CYCLE>.UCB$W_XA_CSRTMP(R5),RO 


; CSR image less GO and CYCLE 

#XA$K_FNCT2,UCB$W_XA_CSRTMP(R5),R2 ; CSR image less FNCT bit 2 
R1,UCB$W_XA_BARTMP(R5) ; Save BAR for error logging 


; At this juncture: 

; RO = CSR image less "GO" and "CYCLE" 

; R1 = Low 16 bits of transfer-bus address 

; R2 = CSR image less FNCT bit 2 

; UCB$L_XA_DPR(R5) = transfer count in words 

; UCB$W_XA_CSRTMP(R5) = CSR image to start transfer with 

; Set DR11-W registers and start transfer. 

; Note that read-modify-write cycles are NOT performed to the DR11-W CSR. 

; The CSR is always written into directly. This prevents inadvertently setting 
; the EIR-select flag (writing bit 15) if error happens to become true. 

DSBINT ; Disable interrupts (powerfail) 

MNEGW UCB$L_XA_DPR(R5),XA_WCR(R4) 

; Load negative of transfer count 
MOVW R1,XA_BAR(R4) ; Load low 16 bits of bus address 

MOVW RO,XA_CSR(R4) ; Load CSR image less GO and CYCLE 

BBC #XA$V_LINK,UCB$L_DEVDEPEND(R5),26$ ; Link mode? 

MOVW R2,XA_CSR(R4) ; Yes, load CSR image less FNCT bit 2 

BRB 126$ ; Only if link-mode bit is set in device characteristics 

26$: 

MOVW UCB$W_XA_CSRTMP(R5),XA_CSR(R4) ; Move all bits to CSR 
; Wait for transfer complete interrupt, powerfail, or device timeout 
126$: 

WFIKPCH XA_TIME_OUT,IRP$L_MEDIA(R3) ; Wait for interrupt 
; Device has interrupted, FORK 

IOFORK ; FORK to lower IPL 
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; Handle request 

MOVZWL 
CLRW 
PURDPR 
BLBS 
MOVZWL 
INCB 

27$: MOVL 

EXTZV 


completion, release UBA resources, check for errors. 


#SS$_NORMAL.-(SP) 

UCB$W_XA_DPRN(R5) 

RO,27$ 

#SS$_PARITY,(SP) 

UCB$W_XA_DPRN+1(R5) 

R1,UCB$L_XA_DPR(R5) 
#VEC$V_DATAPATH,- 
#VEC$S_DATAPATH,- 
CRB$L_INTD+VEC$B_DATAPATH(R3),R0 


Assume success, store code on stack 
Clear DPR number and DPR error flag 
Purge UBA buffered data path 
Branch if no data-path error 
Flag parity error on device 
Flag PDR error for log 
Save data-path register in UCB 
Get data-path-register number 
For error log 


MOVB 

EXTZV 

EXTZV 

INSV 

CMPW 

BGTR 

MOVL 

CLRL 

DECL 

CMPV 

BGTR 

MOVL 

28$: RELMPR 

RELDPR 


RO,UCB$W_XA_DPRN(R5) ; 

#9,#7,UCB$W_XA_BAR(R5),RO 
#4,#2,UCB$W_XA_CSR(R5),R1 
R1,#7,#2,RO 
RO,#496 
28$ 

(R2)[RO],UCB$L_XA_FMPR(R5) 


Save for later in UCB 
; Low bits, final map-register number 
; High bits of map-register number 
Entire map-register number 
Is map-register number in range? 

No, forget it - compound error 
; Save map-register contents 


UCB$L_XA_PMPR(R5) ; Assume no previous map register 

RO ; Was there a previous map register? 

#VEC$V_MAPREG,#VEC$S_MAPREG,- 

CRB$L_INTD+VEC$W_MAPREG(R3),R0 

28$ ; If GTR, no 

(R2)[RO],UCB$L_XA_FMPR(R5) ; Save previous map register contents 

; Release UBA resources 


; Check for errors and return status 



TSTW 

UCB$W_XA_WCR(R5) 


BEQL 

30$ 


MOVZWL 

#SS$_0PINC0MPL,(SP) 

30$: 

BBC 

#XA_CSR$V_ERROR,UCB$W_XA_ 


MOVZWL 

UCB$W_XA_ERR0R(R5),(SP) 


BSBW 

XA_DEV_RESET 

35$: 

BLBS 

(SP),40$ 


JSB 

G~ERL$DEVICERR 

40$: 

BSBW 

DEL.ATTNAST 


JSB 

G~IOC$DIAGBUFILL 


MOVL 

(SP)+,R0 


MULW3 

#2,UCB$W_XA_WCR(R5),R1 


ADDW 

UCB$W_BCNT(R5),R1 


INSV 

R1,#16,#16,R0 


MOVL 

UCB$W_XA_CSR(R5),R1 


BISB 

REQCOM 

#XA_CSR$M_IE,XA_CSR(R4) 


All words transferred? 

Yes 

No, flag operation not complete 
CSR(R5),35$ ; Branch on CSR error bit 
Flag for controller/drive error status 
Reset DR11-W 

Any errors after all this? 

Yes, log them 

Deliver outstanding ATTN ASTs 
Fill diagnostic buffer 
Get final device status 
Calculate final transfer count 

Insert into high byte of IOSB 
Return CSR and EIR in IOSB 
Enable interrupts 
Finish request in exec 


.DSABL LSB 

♦+ 

WORD MODE-Process word mode (interrupt per word) transfer 


FUNCTIONAL DESCRIPTION: 

Data is transferred one word at a time with an interrupt for each word. 
The request is handled separately for a write (from memory to DR11-W 
and a read (from DR11-W to memory). 
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; For a write, data is fetched from memory, loaded into the ODR of the 

; DR11-W and the system waits for an interrupt. For a read, the system 

; waits for a DR11-W interrupt and the IDR is transferred into memory. 

; If the unsolicited interrupt flag is set, the first word is transferred 

; directly into memory without waiting for an interrupt. 

.ENABL LSB 
W0RD_M0DE: 

; Dispatch to separate loops on READ or WRITE 

CMPB #I0$_READPBLK,R2 ; Check for read function 

BEQL 30$ 

; ++ 

; WORD MODE WRITE-Write (output) in word mode 

; FUNCTIONAL DESCRIPTION: 


Transfer the requested number of words from user memory to 
the DR11-W ODR one word at a time, wait for interrupt for each 
word. 


10 $: 


15$: 


BSBW MOVFRUSER ; Get two bytes from user buffer 

DSBINT ; Lock out interrupts 

; Flag interrupt expected 

MOVW R1,XA_0DR(R4) ; Move data to DR11-W 

MOVW UCB$W_XA_CSRTMP(R5),XA_CSR(R4) ; Set DR11-W CSR 

BBC #XA$V_LINK,UCB$L_DEVDEPEND(R5),15$ ; Link mode? 

BICW3 #XA$K_FNCT2,UCB$W_XA_CSRTMP(R5),XA_CSR(R4) ; Clear interrupt FNCT bit 2 

; Only if link mode specified 


Wait for interrupt, powerfail, or device timeout 
WFIKPCH XA_TIME_OUTW,IRP$L_MEDIA(R3) 

Check for errors, decrement transfer count, and loop until complete. 


20 $: 


IOFORK 

BITW 


BEQL 

BRW 

DECW 

BNEQ 


; Fork to lower IPL 

#XA_EIR$M_NEX!- 
XA_EIR$M_MULTI!- 
XA_EIR$M_ACLO!- 
XA_EIR$M_PAR!- 

XA_EIR$M_DLT,UCB$W_XA_EIR(R5) 


20 $ 

40$ 

UCB$L_XA_DPR(R5) 

10 $ 


Any errors? 

No, continue 

Yes, abort transfer. 

; All words trnasferred? 
No, loop until finished. 
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; Transfer is done, clear interrupt expected flag and FORK 


; All 

words read or written in WORD MODE. 

Finish I/O. 

RETURN 

.STATUS: 




JSB 

G ~10C$DIAGBUFILL 

Fill diagnostic buffer if present 


BSBW 

DEL.ATTNAST 

Deliver outstanding ATTN ASTs 


MOVZWL 

#SS$_N0RMAL,RO 

Complete success status 

22$: 

MULW3 

#2,UCB$L_XA_DPR(R5),R1 

Calculate actual bytes transfered 


SUBW3 

R1,UCB$W_BCNT(R5),R1 

From requested number of bytes 


INSV 

R1,#16,#16,RO 

And place in high word of RO 


MOVL 

UCB$W_XA_CSR(R5),R1 

Return CSR and EIR status 


BISB 

#XA_CSR$M_IE,XA.CSR(R4) 

Enable device interrupts 

; + + 

REQCOM 


Finish request in exec 


WORD-MODE READ-Read (input) in word mode 


Functional Description: 

Transfer the requested number of words from the DR11-W IDR into 
user memory one word at a time, wait for interrupt for each word. 

If the unexpected (unsolicited) interrupt bit is set, transfer the 
first (last received) word to memory without waiting for an 
interrupt. 



30$: 


DSBINT UCB$B_DIPL(R5) 


Lock out interrupts 


If an unexpected (unsolicited) interrupt has occured, assume it 
is for this READ request and return value to user buffer without 
waiting for an interrupt. 



BBCC 

#UCB$V_UNEXPT,- 
UCB$W_DEVSTS(R5),32$ 

; Branch if no unexpected interrupt 


ENBINT 


; Enable interrupts 


BRB 

37$ 

; continue 

32$: 

SETIPL 

#IPL$_P0WER 


35$: 




; Wait 

for interrupt, powerfail, or 

device timeout 


WFIKPCH XA_TIME_OUTW,IRP$L_MEDIA(R3) 


; Check for errors, decrement transfer count and loop until done. 


IOFORK ; Fork to lower IPL 

37$: 

BITW #XA_EIR$M_NEX!- 

XA_EIR$M_MULTI!- 
XA_EIR$M_ACLO!- 
XA_EIR$M_PAR!- 

XA_EIR$M_DLT,UCB$W_XA_EIR(R5) ; Any errors? 

BNEQ 40$ ; Yes, abort transfer. 

BSBW MOVTOUSER ; Store two bytes into user buffer 
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; Send interrupt back to sender. 

DSBINT 
MOVW 
BBC 
BICW3 

38$: 

DECW 
BNEQ 
ENBINT 

BRW RETURN.STATUS 

; Error detected in word mode transfer 
40$: 

BSBW DEL.ATTNAST 

BSBW XA_DEV_RESET 

JSB G ~10C$DIAGBUFILL 

JSB G'‘ERL$DEVICERR 

MOVZWL UCB$W_XA_ERROR(R5),RO 
BRW 22$ 

.DSABL LSB 


; Decrement transfer count 
; Loop until all words transferred 

; Finish request in common code 


Deliver ATTN ASTs 
Error, reset DR11-W 
Fill diagnostic buffer if present 
Log device error 

Set controller/drive status in RO 


Acknowledge receipt of last word. 

UCB$W_XA_CSRTMP(R5),XA_CSR(R4) 

#XA$V_LINK,UCB$L_DEVDEPEND(R5),38$ ; Link mode? 

#XA$K_FNCT2,UCB$W_XA_CSRTMP(R5),XA_CSR(R4) ; Yes, clear FNCT 2 

UCB$L_XA_DPR(R5) 

35$ 


MOVFRUSER - Routine to fetch two bytes from user buffer. 
INPUTS: 

R5 = UCB address 
OUTPUTS: 


R1 = Two bytes of data from users buffer 
Buffer descriptor in UCB is updated. 


.ENABL LSB 
MOVFRUSER: 

MOVAL -(SP),R1 
MOVZBL #2,R2 
JSB G~I0C$M0VFRUSER 
MOVL (SP)+,R1 
BRB 20$ 


Address of temporary stack location 
Fetch two bytes 

Call exec routine to do the deed 

Retreive the bytes 

Update UCB buffer pointers 


MOVTOUSER - Routine to store two bytes into users buffer. 

INPUTS: 

R5 = UCB address 

UCB$W_XA_IDR(R5) = Location where two bytes are saved 
OUTPUTS: 

Two bytes are stored in user buffer and buffer descriptor in 
UCB is updated. 
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MOVTOUSER: 

MOVAB 

MOVZBL 

JSB 


20 $: 


30$: 


ADDW 

BICW 

BNEQ 

ADDL 

RSB 


UCB$W_XA_IDR(R5),R1 
#2, R2 

G~I0C$M0VT0USER 


Address of internal buffer 


#2,UCB$W_B0FF(R5) 


; Call exec 

; Update buffer pointers in UCB 
; Add two to buffer descriptor 
*rC<~X01FF>,UCB$W_B0FF(R5) ; Modulo the page size 
30$ ; If NEQ, no page boundary crossed 

#4,UCB$L_SVAPTE(R5) ; Point to next page 


.DSABL LSB 


.PAGE 
.SBTTL 


DR11-W DEVICE timeout 


DR11-W device timeout 

If a DMA transfer was in progress, release UBA resources. 

For DMA or WORD mode, deliver ATTN ASTs, log a device-timeout error. 


; and do a hard 

reset on the controller. 


; Clear 

DR11-W 

CSR 


; Return error 

status 


; Power 

failure 

will appear as a device 

timeout 


.ENABL 

LSB 


XA.TIME. 

_0UT: 


; timeout for DMA transfer 


SETIPL 

UCB$B_FIPL(R5) 

; Lower to FORK IPL 


PURDPR 


; Purge buffered data path in UBA 


RELMPR 


; Release UBA map registers 


RELDPR 


; Release UBA data path 


BRB 

10$ 

; continue 

XA.TIME. 

_0UTW: 


; timeout for WORD mode transfer 


SETIPL 

UCB$B_FIPL(R5) 

; Lower to FORK IPL 

10$: 

MOVL 

UCB$L_CRB(R5),R4 

; Fetch address of CSR 


MOVL 

@CRB$L_INTD+VEC$L_IDB(R4) ,R4 


BSBW 

XA.REGISTER 

; Read DR11-W registers 


JSB 

G~IOC$DIAGBUFILL 

; Fill diagnostic buffer 


JSB 

G~ERL$DEVICTMO 

; Log device timeout 


BSBW 

DEL_ATTNAST 

; and deliver the ASTs 


BSBW 

XA_DEV_RESET 

; Reset controller 


MOVZWL 

#SS$_TIMEOUT,RO 

; Assume error status 


BBC 

#UCB$V_CANCEL,- 




UCB$W_STS(R5),20$ 

; Branch if not cancel 


MOVZWL 

#SS$_CANCEL,RO 

; Set status 

20$: 

CLRL 

R1 



CLRW 

UCB$W_DEVSTS(R5) 

; Clear ATTN AST flags 


BICW 

#<UCB$M_TIM!UCB$M_INT!UCB$M_TIMOUT!UCB$M_CANCEL!UCB$M_POWER> 



UCB$W_STS(R5) 

; Clear unit status flags 


REQCOM 


; Complete I/O in exec 


.DSABL 

LSB 
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PAGE 


.SBTTL 

; + + 

; XA_INTERRUPT, 

XA_INTERRUPT, Interrupt service routine for DR11-W 

Handles interrupts generated by DR11-W 


Functional description: 

This routine is entered whenever an interrupt is generated 
by the DR11-W. It checks that an interrupt was expected. 

If not. it sets the unexpected (unsolicited) interrupt flag. 
All device registers are read and stored into the UCB. 

If an interrupt was expected, it calls the driver back at its 
wait-for-interrupt point. 

Deliver ATTN ASTs if unexpected interrupt. 


; Inputs: 


; 00(SP) = 

; 04(SP) = 

; 08(SP) = 

; 12(SP) = 

; 16(SP) = 

; 20(SP) = 

; 24(SP) = 

; 28(SP) = 

; 32(SP) = 

= Pointer to address of the device IDB 
= saved RO 
= saved R1 
= saved R2 
= saved R3 
= saved R4 
= saved R5 
= saved PSL 
= saved PC 

; Outputs: 



The driver is called at its wait-for-interrupt point if an 
interrupt was expected. 

The current value of the DR11-W CSRs are stored in the UCB 


XA_INTERRUPT: 

MOVL 

movq 

; Interrupt service for DR11-W 
@(SP)+,R4 ; Address of IDB and pop SP 

(R4),R4 ; CSR and UCB address from IDB 


Read the DR11-W device registers (WCR, BAR, CSR, EIR, IDR) and store 


; into UCB. 


BSBW 

XA_REGISTER ; Read device registers 


; Check to see if device transfer request active or not 
; If so, call driver back at wait-for-interrupt point and 
; Clear unexpected interrupt flag. 

20$: BBCC #UCB$V_INT,UCB$W_STS(R5).25$ 

; If clear, no interrupt expected 

; Interrupt expected, clear unexpected interrupt flag and call driver 
; back. 


BICW 

#UCB$M_UNEXPT,UCB$W_DEVSTS(R5) 

MOVL 

JSB 

BRB 

; Clear unexpected interrupt flag 
UCB$L_FR3(R5),R3 ; Restore drivers R3 

<3UCB$L_FPC(R5) ; Call driver back 

30$ 
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; Deliver ATTN ASTs if no interrupt expected and set unexpected 
; interrupt flag. 

25$: 

BISW #UCB$M_UNEXPT,UCB$W_DEVSTS(R5) ; Set unexpected interrupt flag 

BSBW DEL_ATTNAST ; Deliver ATTN ASTs 

BISB #XA_CSR$M_IE,XA_CSR(R4) ; Enable device interrupts 

; Restore registers and return from interrupt 
30$: 

POPR #~M<R0,R1,R2 I R3,R4,R5> ; Restore registers 

REI ; Return from interrupt 

.PAGE 

.SBTTL XA.REGISTER - Handle DR11-W CSR transfers 

; ++ 

; XA_REGISTER - Routine to handle DR11-W register transfers 
; INPUTS: 


R4 - DR11-W CSR address 
R5 - UCB address of unit 

OUTPUTS: 


CSR, EIR, WCR, BAR, IDR, and status are read and stored into UCB. 

The DR11-W is placed in its initial state with interrupts enabled. 

RO - .true, if no hard error 

.false, if hard error (cannot clear ATTN) 

If the CSR ERROR bit is set and the associated condition can be cleared, then 
the error is transient and recoverable. The status returned is SS$_DRVERR. 

If the CSR ERROR bit is set and cannot be cleared by clearing the CSR, then 
this is a hard error and cannot be recovered. The returned status is 
SS$_CTRLERR. 

R0,R1 - destroyed, all other registers preserved. 


XA.REGISTER: 

MOVZWL 

MOVZWL 

MOVW 

BBC 

MOVZWL 

55$: BICW 

BISB 
MOVW 
MOVW 
MOVW 
BBC 

MOVZWL 

60$: MOVW 

MOVW 
MOVW 
MOVW 
RSB 


#SS$_NORMAL,RO 
XA_CSR(R4),R1 
R1,UCB$W_XA_CSR(R5) 
#XA_CSR$V_ERROR,R1,55$ 
#SS$_DRVERR,RO 
#~C<XA_CSR$M_FNCT>,R1 


Assume success 
Read CSR 
Save CSR in UCB 
Branch if no error 
Assume "drive" error 

Clear all uninteresting bits for later 


#<XA_CSR$M_ERR0R/256>,XA_CSR+1(R4) ; Set EIR flag 
XA_EIR(R4),UCB$W_XA_EIR(R5) ; Save EIR in UCB 


R1,XA_CSR(R4) 

XA_CSR(R4),R1 
#XA_CSR$V_ATTN,R1,60$ 

#SS$_CTRLERR,RO 
XA_IDR(R4),UCB$W_XA_IDR(R5) 

XA_BAR(R4),UCB$W_XA_BAR(R5) 

XA_WCR(R4),UCB$W_XA_WCR(R5) 

RO,UCB$W_XA_ERR0R(R5) ; Save status in UCB 


Clear EIR flag and errors 
Read CSR back 

If attention still set, hard error 
Flag hard controller error 
Save IDR in UCB 
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.SBTTL XA.CANCEL, Cancel I/O routine 

++ 

XA_CANCEL, Cancels an I/O operation in progress 
Functional description: 


Flushes Attention AST queue for the user. 

If transfer in progress, do a device reset to DR11-W and finish the 
request. 

Clear interrupt expected flag. 


Inputs: 


R2 

R3 

R4 

R5 


negated value of channel index 
address of current IRP 

address of the PCB requesting the cancel 
address of the device's UCB 


Outputs: 


XA.CANCEL: ; Cancel I/O 

BBCC #UCB$V_ATTNAST,- 

UCB$W_DEVSTS(R5),20$ ; ATTN AST enabled? 

; Finish all ATTN ASTs for this process. 



PUSHR 

#~M<R2,R6,R7> 



MOVL 

R2, R6 ; 

Set up channel number 


MOVAB 

UCB$L_XA_ATTN(R5),R7 ; 

Address of listhead 


JSB 

G~COM$FLUSHATTNS ; 

Flush ATTN ASTs for process 


POPR 

#~M<R2,R6,R7> 


; Check 

to see 

if a data transfer request 

is in progress 

; for this process on this channel 


20$: 

DSBINT 

UCB$B_DIPL(R5) ; 

Lock out device interrupts 


JSB 

G~I0C$Cancel-I/0 ; 

Check if transfer going 


BBC 

#UCB$V_CANCEL,- 
UCB$W_STS(R5).30$ ; 

Branch if not for this guy 

; Force 

timeout 




CLRL 

UCB$L_DUETIM(R5) ; 

Clear timer 


BISW 

#UCB$M_TIM,UCB$W_STS(R5) 

; Set timed bit 


BICW 

#UCB$M_TIMOUT,- 
UCB$W_STS(R5) ; 

Clear timed-out bit 

30$: 

ENBINT 

. 

Lower to FORK IPL 


RSB 

J 

Return 
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.PAGE 

.SBTTL DEL.ATTNAST, Deliver ATTN ASTs 

++ 

DEL.ATTNAST, Deliver all outstanding ATTN ASTs 
Functional description: 

This routine is used by the DR11-W driver to deliver all of the 
outstanding attention ASTs. It is copied from COM$DELATTNAST in 

the exec. In addition, it places the saved value of the DR11-W CSR 
and input-data-buffer register in the AST parameter. 

Inputs: 

R5 = UCB of DR11-W unit 
Outputs: 

R0.R1.R2 Destroyed 
R3,R4,R5 Preserved 


DEL.ATTNAST: 

DSBINT 

BBCC 



UCB$B_DIPL(R5) ; Device IPL 

#UCB$V_ATTNAST,UCB$W_DEVSTS(R5),30$ 

Any ATTN ASTs expected? 


10 $: 


PUSHR 

MOVL 

MOVAB 

MOVL 

BEQL 

BICW 

MOVL 

MOVW 

MOVW 


#~M<R3,R4,R5> 

8(SP),R1 

UCB$L_XA_ATTN(Rl),R2 
(R2), R5 
20 $ 


PUSHAB B~10$ 


Save R3,R4,R5 
Get address of UCB 
Address of ATTN AST listhead 
Address of next entry on list 
No next entry, end of loop 
#UCB$M_UNEXPT,UCB$W_DEVSTS(R1) ; Clear unexpected interrupt flag 
(R5),(R2) ; Close list 

UCB$W_XA_IDR(R1),ACB$L_KAST+6(R5) 

; Store IDR in AST parameter 
UCB$W_XA_CSR(Rl),ACB$L_KAST+4(R5) 

Store CSR in AST parameter 
Set return address for FORK 



FORK 


FORK for this AST 

; AST 

fork procedure 



MOVQ 

ACB$L_KAST(R5),ACB$L_AST(R5) 




; Re-arrange entries 


MOVB 

ACB$L_KAST+8(R5),ACB$B_RM0D(R5) 


MOVL 

ACB$L_KAST+12(R5),ACB$L_PID(R5) 


CLRL 

ACB$L_KAST(R5) 



MOVZBL 

#PRI$_I0C0M,R2 

Set up priority increment 


JMP 

G~SCH$QAST 

Queue the AST 

20$: 

POPR 

#~M<R3,R4,R5> 

Restore registers 

30$: 

ENBINT 


Enable interrupts 


RSB 


Return 
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.PAGE 

.SBTTL XA_REGDUMP - DR11-W register dump routine 

++ 

XA_REGDUMP - DR11-W Register dump routine. 

This routine is called to save the controller registers in a specified 
buffer. It is called from the device error logging routine and from the 

diagnostic buffer fill routine. 

Inputs: 

RO - Address of register save buffer 

R4 - Address of Control and Status Register 

R5 - Address of UCB 

Outputs: 

The controller registers are saved in the specified buffer. 

CSRTMP - The last command written to the DR11-W CSR by 
by the driver. 

BARTMP - The last value written into the DR11-W BAR by 
the driver during a block mode transfer. 

CSR - The CSR image at the last interrupt 

EIR - The EIR image at the last interrupt 

IDR - The IDR image at the last interrupt 

BAR - The BAR image at the last interrupt 

WCR - Word count register 

ERROR - The system status at request completion 
PDRN - UBA data-path-register number 
DPR - The contents of the UBA data-path register 
FMPR - The contents of the last UBA Map register 

PMRP - The contents of the previous UBA Map register 

DPRF - Flag for purge-data-path error 
0 = no purge-data-path error 
1 = parity error when data path was purged 

Note that the values stored are from the last completed transfer 
operation. If a zero transfer count is specified, then the 
values are from the last operation with a non-zero transfer count. 


XA_REGDUMP: 



MOVZBL 

#11,(R0)+ 


MOVAB 

UCB$W_XA_CSRTMP(R5),R1 


MOVZBL 

#8, R2 

10$ 

MOVZWL 

(Rl)+,(RO)+ 


SOBGTR 

R2,10$ 


MOVZBL 

UCB$W_XA_DPRN(R5),(R0) + 


MOVZBL 

#3, R2 

20$ 

MOVL 

(Rl) + , (RO) + 


SOBGTR 

R2,20$ 


MOVZBL 

RSB 

UCB$W_XA_DPRN+1(R5),(RO 


Eleven registers are stored. 

Get address of saved register images 
Return eight registers here 

Move them all 

Save data-path register number 

and three more here 

Move UBA register contents 

; Save data-path-parity-error flag 
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.PAGE 

.SBTTL XA_DEV_RESET - Device reset DR11-W 

++ 

XA_DEV_RESET - DR11-W Device reset routine 

This routine raises IPL to device IPL, performs a device reset to 
the required controller, and reenables device interrupts. 

Input8: 

R4 - Address of control and status register 
R5 - Address of UCB 

Outputs: 

Controller is reset, controller interrupts are enabled 


XA_DEV_RESET: 


PUSHR #~M<R0,R1,R2> ; Save some registers 

DSBINT ; Raise IPL to lock all interrupts 

MOVB #<XA_CSR$M_MAINT/256>,XA_CSR+1(R4) 

CLRB XA_CSR+1(R4) 





Must delay here depending on reset interval 


TIMEDWAIT TIME=#XA_RESET_DELAY 

MOVB #XA_CSR$M_IE,XA.CSR(R4) 

ENBINT 

POPR #~M<RO,R1,R2> 

RSB 


Number of 10 micro-sec intervals to wait 

Reenable device interrupts 
Restore IPL 
Restore registers 


XA.END: 

.END 



End of driver label 
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This appendix describes the data structures and macros used 
by DIGITAL for its standard magnetic tape and disk products. 
Customers using the DR32 should use equivalent techniques. 

The MASSBUS adapter (MBA) is the hardware interface 
between the backplane interconnect and MASSBUS storage 
devices. The MASSBUS is the communication path linking the 
MASSBUS adapter to the mass storage devices. 

The MASSBUS adapter performs the following functions that 
allow communication between devices and memory: 

• Mapping of virtual address to physical page-frame numbers 

• Buffering of data for transfers between main memory and 
the MASSBUS 

• Transfer of interrupts from MASSBUS devices to the 
backplane interconnect 

A MASSBUS adapter supports any combination of up to eight 
device controllers. Typical MASSBUS controllers include 
the TM03 tape controller; the RP06, RM03, and RM80 disk 
controllers; and the DR32, which is a general purpose interface 
that acts as a controller for one or more nonstandard devices. 
Only one controller can transfer data over the MASSBUS at a 
time. 

The TM03 tape controller supports up to eight tape drives. In 
contrast to tape controllers, there is a one-to-one relationship 
between a disk controller and its device; each controller 
supports only one disk drive. The VAX/VMS system interprets 
and maintains the I/O database differently depending upon 
whether the controller is single or multiunit. 

Each MASSBUS controller connected to a MASSBUS adapter is 
assigned a unit number in the range 0 to 7. The method of unit 
number assignment is controller specific, but you can obtain 
the number from either unit plugs or switch packs. In the case 
of a controller for several devices, the unit number is distinct 
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from the subunit numbers assigned to the individual drives 
connected to the controller. 

Figure G-l illustrates a possible MASSBUS configuration. 


Figure G-1 MASSBUS Configuration 



SUB-UNIT SUB-UNIT SUB-UNIT SUB-UNIT 
0 12 3 
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G.1 MASSBUS Adapter Registers 

The MASSBUS adapter has three sets of registers: 

• The MASSBUS adapter's registers 

• External registers for each device (controller) on the 
MASSBUS 

• 256 mapping registers 

To allow competing devices to share these resources, access to 
and modification of all MASSBUS adapter registers (internal, 
external, and mapping registers) are governed by certain rules 
and conventions. In particular, access to registers might, at 
times, require ownership of either the device controller or the 
MASSBUS adapter itself, or both. Subsequent sections in this 
chapter discuss the methods of obtaining such ownership of 
these shared resources. 
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MASSBUS adapter external registers are device dependent 
and accessible whether or not the driver owns the MASSBUS 
adapter. However, in the case of multiunit MASSBUS adapter 
controllers, the driver might need to own the controller before 
it can gain access to a register. 

MASSBUS adapter external registers are each 16 bits wide, but 
they must be accessed as longwords. When a driver reads an 
external register, the MASSBUS adapter concatenates the high 
order 16 bits of the MBA's status register (one of the MBA's 
internal registers) to the contents of the specified external 
register. A diagram of the resulting longword is shown below. 


Figure G—2 1 

MASSBUS External-Register Longword 

31 16 

15 0 


MBA’s status register 

External register 


Bits 31 - 16 

contents 
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On a write to an external register, the MASSBUS adapter uses 
the low order 16 bits of the longword source operand to update 
the external register. 

MASSBUS adapter internal and mapping registers are 32 
bits in length. They must be accessed as longwords or the 
processor will signal a machine check exception. The driver 
for a MASSBUS device must obtain exclusive ownership of the 
MASSBUS adapter before modifying any of the MBA's internal 
or mapping registers. 

Bits 21 through 30 of each of the MBA's mapping registers are 
reserved; they cannot be written. Use of the MBA's mapping 
registers is analogous to use of the UNIBUS adapter's mapping 
registers with the following exceptions: 

• Because the MASSBUS can handle only one transfer at 
a time, ownership of the MASSBUS adapter implies 
ownership of all its mapping registers. Thus, the driver 
need not independently request mapping registers. 
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G.1.1 


• The MBA's mapping registers do not contain a byte-offset 
field. The driver loads the full MASSBUS adapter virtual 
address, including the byte alignment, into the MASSBUS 
adapter virtual address register (VAR, one of the MBA's 
internal registers) at the start of a data transfer. Use of the 
VAR register is described below. 

• The MBA's mapping registers do not contain a data path 
field; the MASSBUS adapter has a single data path, 
and ownership of the adapter implies ownership of the 
path. Thus, the driver need not allocate the data path 
independently. 


Loading MASSBUS Adapter Registers 

To prepare for a data transfer over the MASSBUS, the driver 
that owns the MASSBUS adapter uses the LOADMBA macro 
to load the MBA's mapping registers and associated internal 
registers. The LOADMBA macro invokes the subroutine 
IOC$LOADMBAMAP, which performs the following steps: 


• Determines the number of mapping registers needed to map 
the data area by adding the contents of UCB$W_BCNT to 
UCB$W_BOFF, adjusting the sum to the next even multiple 
of 512, and dividing the result by 512. 

• Loads the specified number of mapping registers, beginning 
with mapping register 0, with the contents of the page-table 
entries to which UCB$L_SVAPTE points. This step maps 
the data area for the transfer into the low portion of the 
MBA's virtual address space. The routine also loads the next 
mapping register beyond the number used to map the data 
area with zeros (an invalid map entry). This procedure stops 
the transfer should a hardware failure occur. 

• Loads the VAR register with the zero extended contents of 
UCB$W_BOFF. Because the first byte of the data area is 
located at offset UCB$W_BOFF within the page of memory 
mapped by mapping register 0, the UCB$W_BOFF contains 
the virtual address of the start of the data area in MASSBUS 
adapter virtual address space. 

• Loads the complement (negative) of UCB$W_BCNT into the 
MBA's byte-count register (BCR). 
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Note that if a driver is to perform a data transfer in the 
reverse direction (for example, read reverse on a tape) it 
must modify the contents of the VAR, as established by 
IOC$LOADMBAMAP, so that it points to the last byte of the 
data area. This is done by adding one less than the contents of 
UCB$W_BCNT to the contents of the VAR register. 

During the progress of a data transfer over the MASSBUS, the 
VAR register is continuously updated so that it points to the 
current position in the data area. The VAX Hardware Handbook 
illustrates the mapping of the contents of the VAR register into 
physical memory. 


G.1.2 MASSBUS Adapter Registers and Offsets 

During system initialization, VAX/VMS builds an adapter- 
control block (ADP) a channel-request block (CRB), and an 
interrupt-dispatch block (IDB) for each MASSBUS adapter. 

The system also allocates 4K bytes of system virtual address 
space for the adapter's register I/O space. The base of this I/O 
register virtual address space is placed in IDB$L_CSR. Thus, 
you can access MASSBUS adapter registers using the base 
register virtual address plus some offset. The $MBADEF macro 
defines the offsets for MASSBUS adapter registers. The major 
symbols defined by this macro are shown in Table G-l. 


Table G-1 Major Offsets Defined by $MBADEF 


Symbol 

MBA Register Name 

Hex Offset 

MBA$I_CSR 

Configuration register 

0 

MBA$I_CR 

Control register 

4 

MBA$I_SR 

Status register 

8 

MBA$I_VAR 

Virtual-address register 

C 

MBA$I_BCR 

Byte-count register 

10 

MBA$L_DR 

Diagnostic register 

14 

MBA$I_SMR 

Selected mapping register 

18 

MBA$I_CAR 

Command-address register 

1C 

MBA$I_ERB 

External register base 

400 

MBA$I_AS 

Attention-summary register 

414 

MBA$I_MAP 

Base of mapping registers 

800 
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The MASSBUS adapter's internal registers occupy the low order 
1024 bytes of address space even though there are only eight 
internal MBA registers. Beyond the internal registers, there are 
eight blocks of 32 longwords (128 bytes) each, one block for 
each of the eight device controllers that can be connected to a 
single MASSBUS adapter. Each of these blocks provides space 
for the device registers of each controller. Beyond the device¬ 
register space is the area reserved for the MASSBUS adapter's 
256 mapping registers. 

Figure G-3 illustrates the relative positions of the MASSBUS 
adapter's registers and the values device drivers use to gain 
access to them. The base address of the MASSBUS adapter's 
address space, stored in IDB$L_CSR, is the address of the 
first of the MASSBUS adapter's internal registers. IDB$L_ 

CSR represents the internal register's virtual location, while 
the MBA$L_ symbols represent register values as defined 
by $MBADEF. Note that the MASSBUS adapter's register 
space occupies only the first 3K bytes out of the 8K bytes 
allotted to physical, I/O address space, but that, by convention, 
VAX/VMS allocates 4K bytes of virtual addresses to each 
MASSBUS adapter. 

To address a mapping register in the MASSBUS adapter, the 
driver constructs the following address: 

IDB$L_CSR + MAP$L_MAP + mapping register index 


To address a device register, the driver constructs the following 
address: 

IDB$L_CSR + MAP$L_ERB + (unit number * X~80) + register displacement 


An individual driver should define offsets for the registers of 
its device. During execution, the driver computes a register 
address by summing the MBA's starting virtual address (the 
contents of IDB$L_CSR), MBA$L_ERB, the unit number of the 
device controller multiplied by 80 (hex), and the offset of the 
specified register. 

The attention-summary register, as shown in Table G-l, 
appears to reside within the external-register space reserved 
for MASSBUS adapter controller 0. Actually, the attention- 
summary register is a composite register. Each of the 
MASSBUS adapter's controllers contributes one bit of 
information to the register. This composite register appears 


G—6 





MASSBUS Adapter 


Figure G-3 Location of MASSBUS Registers in Physical Address 
Space 


IDB$I_CSR 

MASSBUS 

INTERNAL REGISTERS 
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UNIT 7 
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DEVICE REGISTERS 
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MAP REGISTERS 



1024 UNUSED BYTES 




J 
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in each of the eight device register spaces at offset 10 (hex) 
from the base of the device registers for that device. Thus, 
MBA$L_AS can be defined as either 410, 490, 510, 590, and so 
on. For convenience, it has been defined as 410 (hex). 
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G.1.3 Modification of MASSBUS Adapter Registers 

The driver for a MASSBUS device must obtain ownership of 
the MBA before modifying any of the MBA's internal registers 
or mapping registers. A driver obtains ownership of the MBA 
by invoking either the REQPCHAN macro or the REQSCHAN 
macro, depending on whether the device is connected to a 
single unit MASSBUS controller or a multiunit MASSBUS 
controller. For dedicated controllers, invoke the REQPCHAN 
macro. Because the controller is dedicated to its single device, 
there is never any contention for the controller. 

For multiunit devices, however, invoke the REQSCHAN macro 
to obtain MBA ownership because several devices can share the 
controller, and so must contend for its use. The controller for 
several devices relegates the MASSBUS adapter to a secondary 
position. Thus, for multiunit controllers, invoke REQPCHAN 
to gain ownership of the controller, and invoke REQSCHAN to 
obtain the MASSBUS adapter. 


G.2 I/O Database for MASSBUS Devices 

During initialization, the system creates an adapter-control 
block, a channel-request block, and an interrupt-data block for 
each MASSBUS adapter included in the configuration. The 
driver-loading procedure subsequently builds additional data 
structures for each device controller connected to a MASSBUS 
adapter. The type of structure created depends upon whether 
the device controller is a dedicated controller or the controller 
of several devices. 

The system builds a unit-control block for each single unit 
controller. Figure G-4 illustrates the I/O database for a 
MASSBUS adapter with one dedicated controller attached 
to it. Note that the ADP, CRB, and IDB all correspond to the 
MASSBUS adapter and can logically be considered a single, 
extended data block. The UCB corresponds to the device 
/controller pair. Because of the one-to-one correspondence 
between a dedicated controller and its device, the system does 
not need to distinguish between the two and thus does not 
maintain separate data blocks for each piece of hardware. 
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Figure G-4 I/O Database for MASSBUS Disk Unit 
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A controller of several devices, however, requires separate data 
structures for the controller and each of its subunits (devices). 
The driver-loading procedure builds a CRB/IDB pair for the 
controller, as well as a UCB for each subunit. Figure G-5 
shows the I/O database created for a MASSBUS adapter with 
one disk unit and two tape units. 
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Figure G—5 I/O Database for MASSBUS Disk and Tape Units 
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Figure G-5 does not include several pointers used in interrupt 
dispatching. In particular, the IDB associated with the 
MASSBUS adapter maintains an array of up to eight longwords 
that point to the data structures associated with the eight 
possible MASSBUS controllers attached to the MASSBUS. 

For dedicated controllers, the IDB longword points to the 
device's UCB, whereas, for a controller for several devices, 
the longword (or longwords) points to a field within the CRB 
associated with the controller. The low bit of this longword, 
when set, indicates a multiunit vector. The software checks this 
bit to determine whether the longword points to a single UCB 
or a multiunit CRB. 


G—10 





































MASSBUS Adapter 


Also not pictured in Figure G-5 is how multiunit interrupt-data 
blocks also maintain an array of longwords. Each longword 
points to the individual unit-control blocks for the units 
attached to the controller. Figure G-6 illustrates in more 
detail the set of I/O data structures for the MASSBUS adapter 
and its devices. 


Figure G-6 I/O Data Structures Used in Dispatching an Interrupt 


ADP 





G.3 MASSBUS Adapter Operations 

The MASSBUS accepts two kinds of operations: data transfer 
operations and nondata transfer operations. Data transfer 
operations require the use of MASSBUS adapter shared 
resources, while nondata transfers do not. 
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Before a driver can activate a data-transfer operation on the 
MASSBUS, the driver must request and receive ownership of 
the MASSBUS adapter on behalf of the device unit. However, 
drivers must not initiate nondata transfer operations while they 
have control of the MASSBUS adapter. Section F.4.1 explains 
this statement further. 

The MASSBUS adapter generates interrupts when data transfers 
terminate and when attention conditions arise on devices. 
When an interrupt occurs on the MASSBUS adapter, the 
MASSBUS adapter's interrupt dispatcher determines whether 
the interrupt is for a data transfer or an attention condition. 

Data-transfer interrupts occur when a data transfer either 
completes or is aborted. When the interrupt occurs, the MBA's 
status register (SR) contains information about the condition 
that caused the interrupt. 

Attention interrupts occur when nondata transfers on 
MASSBUS devices terminate, or when the device undergoes 
an exceptional condition, such as coming on line. 

The MASSBUS adapter's attention-summary register controls 
attention-interrupt handling. This register contains eight bits 
of data, one for each of the eight possible controllers that can 
be connected to the MASSBUS adapter. When a device incurs 
an attention condition, the hardware sets the corresponding bit 
in the attention-summary register and generates a MASSBUS 
adapter interrupt. 

If the attention condition occurs while a data-transfer operation 
for another device is in progress, the hardware sets the bit in 
the attention-summary register but suppresses the attention 
interrupt. The interrupt generated when the data transfer is 
completed allows the MASSBUS adapter's interrupt dispatcher 
to gain control, handle the data-transfer interrupt, check the 
attention-summary register and then invoke the proper driver 
to handle the interrupt. 
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G.4 MASSBUS Adapter's Interrupt Dispatching 

When interrupts occur on the MASSBUS adapter, the 
MASSBUS adapter's interrupt dispatcher gains control. This 
routine first determines whether the interrupt is the result of a 
data transfer or an attention condition. The routine checks to 
see if the MASSBUS adapter is owned and, if so, by whom. 


G.4.1 Checking for MASSBUS Adapter Ownership 

There are two conditions by which the interrupt dispatcher can 
determine that the interrupt is an attention interrupt: 

• If the MASSBUS adapter is not owned 

• If the MASSBUS adapter is owned, but the owner is not 
expecting an interrupt (UCB$M_INT in UCB$W_STS is 
clear) 

When the MASSBUS adapter is owned and the owner expects 
an interrupt, the interrupt is assumed to be the result of a data 
transfer operation. 

As mentioned earlier, a driver must not initiate nondata 
transfers on the MASSBUS adapter while it owns the adapter. 
For example, consider a MASSBUS adapter attached to two disk 
units, A and B. Disk A is performing an IO$_SEEK (a nondata 
transfer operation that completes fairly quickly), while at the 
same time, disk B is performing an IO$__RECAL operation 
(a nondata transfer operation that takes about 0.5 seconds to 
complete). 

The driver for disk A correctly initiates its operation without 
obtaining possession of the MASSBUS adapter channel, but the 
disk B driver initiates its operation while it owns the MASSBUS 
adapter. Both of these operations, upon completion, set the 
bit in the attention-summary register that corresponds to their 
respective drive units, and initiate an interrupt. We will assume 
that disk A's IO$_SEEK is completed first. The operation sets 
disk A's bit in the attention-summary register and generates the 
MASSBUS adapter's interrupt. 
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G.4.2 


The MASSBUS adapter's interrupt dispatcher finds that the 
adapter is owned, and that the owner is expecting an interrupt. 
Therefore, the interrupt dispatcher incorrectly assumes that it 
is handling a data-transfer interrupt, and, moreover, that this 
interrupt is the one for which the owner of the MBA is waiting. 

So, the MASSBUS adapter's interrupt dispatcher returns control, 
through the fork block in the MASSBUS adapter owner's UCB, 
to the driver for disk B, even though disk B's operation has not 
completed. The disk B driver will now incorrectly assume that 
the device has completed its operation, which can cause serious 
problems. 


Dispatching the Interrupt 

Once the MASSBUS adapter's interrupt dispatcher determines 
the type of interrupt, it dispatches the interrupt to the driver. 
The interrupt dispatcher handles attention interrupts and 
data-transfer interrupts in the same way, with one exception: 
On an attention interrupt, the interrupt dispatcher clears the 
MASSBUS adapter's status register before dispatching the 
interrupt to the driver. The status register contains information 
used only in data-transfer-interrupt dispatching. 

How the interrupt dispatcher dispatches the interrupt to the 
driver differs depending on the type of controller. 

The MASSBUS adapter's interrupt dispatcher handles a solicited 
interrupt on a dedicated controller by transferring control to the 
driver through the fork block in the UCB. On unsolicited 
interrupts on dedicated controllers, the interrupt dispatcher calls 
the driver's unsolicited-interrupt-servicing routine. 

On dedicated controllers, the MASSBUS adapter's interrupt 
dispatcher always clears the attention bit in the attention- 
summary register before it calls back the driver after an 
interrupt. 

Dispatching interrupts to the driver of a device that shares its 
controller with several other devices differs in two ways from 
dispatching interrupts to the driver of a device with a dedicated 
controller. 
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First, the interrupt dispatcher never clears the attention bit. 
This task is left to the driver because some controllers that 
control more than one device use this bit to synchronize their 
activities, and guarantee the integrity of device registers only 
while the bit is set. If the interrupt dispatcher clears the bit 
before returning control to the driver, the driver can no longer 
rely on the contents of the device's registers. 

Second, a controller that controls several devices needs another 
interrupt dispatcher to handle simultaneous requests from its 
several subunits. This second-level interrupt dispatcher resides 
in the driver. After an interrupt, the MASSBUS adapter's 
interrupt dispatcher indirectly calls this second, driver's 
interrupt dispatcher using code in the controller's channel- 
request block. The driver-loading procedure installs this code 
when it establishes the I/O database. 


G.5 Special MBA Considerations for Drivers 

MASSBUS adapter considerations affect a driver's device 
unit initialization routine, start-I/O routines and, for 
multiunit controllers only, the driver's DPTAB macro. MBA 
considerations also affect interrupt handling, as described 
in Section F.4.2. The next sections in this chapter discuss 
programming details for writing a MASSBUS device driver. 


G.5.1 Considerations for Unit-Initialization Routines 

All drivers for MASSBUS adapter devices initialize two fields in 
the UCB (as well as initializing device-specific fields): UCB$B_ 
SLAVE and UCB$B_SLAVE+1. The first of these fields should 
contain the controller's MASSBUS adapter unit number, which 
marks the controller's position on the MASSBUS adapter. The 
second of these contains the offset, in longwords, from the start 
of the MASSBUS adapter's external registers to this controller's 
device registers. The value of this longword offset is always 32 
times the unit number of the controller. 

Initialization of a device attached to a dedicated controller 
is simple because the device unit number and the controller 
position number on the MASSBUS adapter are always equal. 

To initialize the field UCB$B_SLAVE, copy to it the contents 
of UCB$W_UNIT. To initialize UCB$B_SLAVE+1, multiply 
its contents by 32. The driver later uses this information to 


G-15 







MASSBUS Adapter 


compute a pointer to this device's registers. By convention, R4 
points to the MASSBUS adapter configuration register, and R5 
points to the UCB of this device. 

Thus, the following two instructions cause R3 to point to the 
device registers during normal system operation: 

MOVZBL UCB$B_SLAVE+1(R5),R3 
MOVAL MBA$L_ERB(R4)[R3] ,R3 

For devices connected to a controller that controls several 
devices, determination of the controller's MBA position is more 
complex. When the unit-initialization routine is invoked, the 
following values are in the following registers: 

R3 Address of controller's device registers 

R4 Address of the MBA's configuration register 
R5 Address of device's UCB 

The driver computes the MBA position of the controller by 
using R3 and R4 to determine the number of bytes from the 
start of the MBA's external registers to the start of the device's 
device registers. The difference, when divided by 128, is the 
controller's MBA position number. 


G.5.2 The MASSBUS Adapter and the I/O Database 

The unit-control block of a device connected to a single-unit 
controller, at offset UCB$L_CRB, contains the address of the 
MASSBUS adapter's channel-request block. This CRB in turn 
contains, at offset CRB$L_INTD+VEC$L_IDB, the address of 
the MASSBUS'S interrupt-dispatch block. This IDB points to 
the base address of the MASSBUS adapter registers at offset 
IDB$L_CSR. 

A controller that controls several devices maintains a more 
complicated I/O database. The device UCB, at offset UCB$L_ 
CRB, points to the controller's channel-request block, and this 
structure points to the CRB for the MASSBUS adapter at offset 
CRB$L_LINK. Also, the controller's CRB points to its own IDB 
at offset CRB$L_INTD+VEC$L_IDB. This IDB points to the 
controller's device registers at offset IDB$L_CSR. 
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Thus, the unit-control block for a device always points to 
that device's primary channel-request block, whether it is the 
MASSBUS adapter's CRB or the controller's CRB. The primary 
channel-request block points to the secondary CRB, if one exists 
for the device. 

Figure G-6 shows these relationships among I/O data 
structures. 


G.5.3 Considerations for the Start-I/O Routine 

Depending on the function being executed, the start-I/O routine 

for a MASSBUS device performs all or some of the following 

tasks: 

• Requests controller data channel(s) as described in 
Section F.5.3.1 

• Clears errors on the MASSBUS adapter by setting the value 
-1 into the MBA's status register; this is a write-ones-to-clear 
register (MASSBUS device registers and the MBA's registers 
are all longwords) 

• Invokes the LOADMBA macro to load the MBA's mapping 
registers as described in Section F.5.3.2 

• Loads device registers to start the function 

• Waits for a device interrupt or timeout 

• Releases controller data channel(s) as described in 
Section F.5.3.3 

• Finishes the request like other drivers 


G.5.3.1 Requesting Controller Data Channels 

Device drivers for MASSBUS devices must request and receive 
ownership of the MASSBUS adapter channel before loading 
the MBA's internal registers or mapping registers. In addition, 
drivers for devices connected to multiunit controllers must 
obtain ownership of the controller channel before modifying 
the contents of controller registers that can be shared among 
the units connected to the controller. 


Drivers for dedicated controllers must request ownership 
of the MASSBUS adapter channel by invoking the macro 
REQPCHAN. 
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Device drivers for controllers that control several devices 
invoke the REQPCHAN macro when the operation requires 
ownership of only the primary channel (the controller's 
channel). However, if the operation requires ownership of both 
primary and secondary channels (a data transfer operation), the 
driver must first obtain the controller channel and then request 
the MASSBUS adapter channel by invoking the REQSCHAN 
macro. 

Again, the driver needs ownership of both channels only when 
performing a data transfer, and must release the channels 
before initiating a nondata transfer. Thus, a driver must obtain 
ownership of the MASSBUS adapter channel sometime before 
initiating a data transfer and must either not own the channel 
or release such ownership before it invokes the WFIKPCH 
macro following the start of a nondata transfer operation. 


G.5.3.2 Loading mapping registers 

MASSBUS device drivers invoke the LOADMBA macro before 
they initiate a data transfer to load the MBA's mapping 
registers, the MBA's virtual-address register, and the MBA's 
byte-count register. Drivers cannot modify these registers 
during a transfer. The LOADMBA macro expects the following 
register contents: 

• The address of the MBA's Configuration Register in R4 

• The address of the device UCB in R5 

LOADMBA preserves the contents of R3 but modifies RO 
through R2. The macro performs the following steps: 

1 Uses the contents of UCB$W_BCNT and UCB$W_BOFF to 
determine the number of pages that contain pieces of the 
I/O buffer 

2 Beginning with the page-table entry to which UCB$L_ 
SVAPTE points and continuing for the number of page-table 
entries determined in the step above, copies the page-frame 
numbers from the page-table entries to the corresponding 
mapping registers, starting at mapping register 0 

3 Deposits an invalid value into the mapping register that 
immediately follows the last mapping register loaded with a 
PFN so that a hardware fault does not modify memory 
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4 Moves the negative value of the transfer byte count 
(UCB$W_BCNT) into the MBA's byte-count register 

5 Moves the byte offset in the first page of the transfer 
(UCB$W_BOFF) into the MBA's virtual-address register 

6 Returns to the start-I/O routine that invoked it 

If the I/O operation about to be initiated by the driver is a 
reverse operation (a read-reverse on tape), the driver must 
modify the contents of the MBA's virtual-address register set 
up by LOADMBA. Because reverse operations access the I/O 
buffer from its highest address through its lowest address, the 
value to be loaded into the MBA's virtual-address register must 
be the virtual address, in MBA's virtual memory, of the last 
byte of the buffer. This number is equal to one less than the 
sum of the contents of UCB$W_BOFF and UCB$W_BCNT. 


G.5.3.3 Releasing Controller Data Channels 

The driver releases the controller data channels by invoking the 
RELCHAN macro. RELCHAN releases all controller channels 
(both primary and secondary) currently owned by the device. 
To release only the secondary channel and retain ownership 
of the primary channel, a driver can invoke the RELSCHAN 
macro. 


G.5.4 Considerations for the DPTAB Macro 

The device driver for a MASSBUS device that shares its 
controller with other devices must set the DPT$M_SUBCNTRL 
bit in the FLAGS argument of the DPTAB macro. Setting 
this bit causes the driver-loading procedure to create a second 
channel-request block and an interrupt-data block for the 
controller. 
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G.6 Interrupt-Servicing Routines for MASSBUS Devices 

The VAX MASSBUS interrupt dispatcher (MBA$INT) gains 
control when it receives an interrupt from the MASSBUS 
adapter. Because data transfers in progress suppress attention 
interrupts on the MASSBUS adapter, and because several 
devices can request attention simultaneously, some device 
drivers might need to be informed of the interrupt. 

MBA$INT determines which drivers should be invoked as 
a result of the interrupt and then passes control to these 
drivers. For data-transfer interrupts, MBA$INT preserves 
the value contained in the MBA's status register at the time of 
the interrupt so that the driver can have access to this value. 

For I/O operations that involve no data transfer, MBA$INT 
clears this register before invoking the driver. MBA$INT only 
preserves the contents of registers R2 through R5. Drivers that 
use other registers must save the contents of those registers, 
and must restore them before exiting the interrupt-servicing 
routine. 


G.6.1 Transferring Control to the Interrupt-Servicing 

Routine 

The method by which MBA$INT invokes a driver depends 
upon whether the driver serves a device connected to a 
dedicated controller or a device that shares its controller with 
several other devices. Furthermore, if the device is connected to 
a dedicated controller, the method of transfer from MBA$INT 
to the driver depends upon whether or not the interrupt is 
expected. 

For a device on dedicated controller when the driver is 
expecting an interrupt, MBA$INT restores the driver context 
saved in the UCB fork block and transfers control (using a JSB 
instruction) to the instruction that follows the wait-for-interrupt 
instruction. 

For a device on a dedicated controller when the driver is not 
expecting interrupts, MBA$INT obtains the address of the 
driver's unsolicited-interrupt routine from the driver-dispatch 
table and calls the routine. 
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G.6.2 


For a device that shares its controller several other devices, 
MBA$INT transfers control to the driver's interrupt-servicing 
routine by simulating a direct transfer, through an interrupt 
vector, to the controller's CRB. The CRB contains code that 
transfers control to the interrupt-servicing routine. 

MBA$INT first pushes the processor status longword (PSL) 
onto the stack. The routine then calls (with a JSB instruction 
that leaves an address within MBA$INT on the stack) the code 
within the CRB. This code contains the following sequence 
of instructions, where XX$INT is the address of the interrupt¬ 
servicing routine and XX$IDB is the address of the controller's 
IDB: 

PUSHR #M<R2,R3.R4,R5> 

JSB XX$INT 

.LONG XX$IDB 

The execution of the above sequence of instructions, plus the 
instructions executed by MBA$INT (the pushing of the PSL 
onto the stack and the JSB) places a simulated interrupt-frame 
onto the stack, including a saved PSL, a saved PC, saved 
registers and pointer to a pointer to the IDB. 


Returning Control to MBA$INT 

The way in which a driver returns control to MBA$INT 
depends on the way in which MBA$INT invoked it. Drivers 
for dedicated controller devices return to MBA$INT through an 
RSB instruction, although the RSB can execute as a result of the 
driver's invoking the IOFORK macro. 

Drivers of devices that share a controller return control to 
MBA$INT by removing the indirect pointer to the IDB from 
the top of the stack, restoring registers R2 through R5, and 
executing an REI instruction. This sequence, executed within 
the driver's interrupt-servicing routine, eliminates the simulated 
interrupt-frame from the stack before returning to MBA$INT. 
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G.6.3 


Considerations for Interrupt-Servicing Routines 

Drivers for dedicated controller devices attached to the 
MASSBUS do not have interrupt-servicings routines. Instead, 
MBA$INT handles all the functions that a driver interrupt¬ 
servicing routine normally provides. 

Drivers of devices that share a controller on the MASSBUS 
must have their own interrupt-servicing routines. In general, 
these routines perform the same functions as the interrupt¬ 
servicing routines for UNIBUS devices (discussed in Chapter 
11). However, UNIBUS and MASSBUS drivers diverge in two 
areas. 

One difference between UNIBUS and MASSBUS drivers 
concerns the number of registers saved by the interrupt¬ 
servicing routine. When the interrupt dispatcher transfers 
control to a MASSBUS driver interrupt-servicing routine, 
registers R2 through R5 are pushed onto the stack. UNIBUS 
drivers save RO through R5. 

After handling an interrupt, both MASSBUS and UNIBUS 
driver interrupt-servicing routines execute an REI instruction. 
For UNIBUS devices, the REI dismisses a real interrupt, whereas 
the MASSBUS driver's REI returns control to MBA$INT. 
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UNIBUS Addresses for VAX 
Processors 


This appendix lists the starting physical addresses for UNIBUS 
adaptors on VAX-11/780, VAX-11/782, VAX-11/785, VAX- 
11/750, VAX-11/730, and VAX-11/725 processors. The 
addresses in the table below are given in hexadecimal. 


UNIBUS 

adapter 

number 

VAX-11/725 
VAX-11/730 

VAX-11/750 

VAX-11/785 
VAX-11/782 
VAX-11/780 

MicroVAX 1 

0 

00FC0000 

00FC0000 

20100000 

20000000 

1 

- 

00F80000 

20140000 

- 

2 

- 

- 

20180000 

- 

3 

- 

- 

201C0000 

- 


Note: The macros $IO730DEF, $IO750DEF, $IO780DEF, and 

IOUVIDEF define symbolic constants for the base address of 
UNIBUS space 0. 
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Device Driver Entry Points 


This appendix describes the entry points used by VMS to 
activate a device driver. 


1.1 FDT Routines 


This portion of a driver prepares for a device operation. The 
operation might or might not involve a transfer of data. 

How to Specify This Entry Point 


Use the FUNCTAB macro to specify the set of FDT routines that 
preprocess requests for I/O activity of a given type. Specify the 
names of the routines in the order in which you want them to 
execute for each type of I/O operation. 

Inputs 


Register Contents 


RO 

R3 

R4 

R5 

R6 

R7 

R8 

AP 



The address of the FDT routine being called 
The address of the IRP for the current I/O request 

The address of the PCB of the requesting (current) 
process 

The address of the UCB of the device on which I/O 
activity is requested, the device assigned to the 
user-specified process-l/O channel 

The address of the CRB that describes the user- 
specified process-l/O channel 

The number of the bit that specifies the code for the 
I/O function requested 

The address of the entry in the FDT that dispatched 
control to this FDT routine 

The address of the first function-dependent 
parameter specified in the QIO request. 
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Outputs 

No direct outputs are required, but control must either be 
returned to the QIO code by means of a RSB instruction, or 
passed, by means of a JMP instruction, to a routine that queues 
the IRP or to a routine that finishes or aborts the I/O request. 

Use of Registers 

FDT routines must preserve the contents of R3 through R8, the 
AP, and the FP. 

Context 

FDT routines execute in the context of the process that 
requested the I/O activity. FDT routines must not lower 
IPL below IPL$_ASTDEL. If they raise IPL, they must lower it 
to IPL$_ASTDEL before passing control to any other code. If 
an FDT routine alters the stack, it must restore the stack before 
returning control to the caller of the routine. 

IPL on Entry and Exit 

FDT routines are called at IPL$_ASTDEL and must exit at 
IPL$_ASTDEL. 

Which VAX/VMS Routines Use This Entry Point 

The QIO system service calls this entry point from the executive 
module SYSQIOREQ. 

Exiting Mechanisms 

The way in which FDT routines exit depends on what I/O 
activity is requested. The choices are listed below. 

For each function a device supports, a set of FDT routines must 
provide preprocessing of requests for that function. Except for 
the last FDT routine in such a set, each routine must return 
control to its caller by means of in RSB instruction. The last 
must exit by means of one of the routines listed below, not by 
means of an RSB instruction. 
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Exit Mechanism 

Function 

EXE$ABORTIO 

Aborts an I/O request and returns to the 
caller of the QIO system service, as status 
information, the contents of RO 

EXE$ ALT QUEPKT 

Queues an IRP to the driver's alternate entry 
point without checking the status of the 
device 

EXE$FINISHIO 

Finishes the I/O processing, returning a 
quadword of status information to the caller 
of the QIO system service; the information 
is returned in the IOSB specified in the 
call to QIO, and the status information is 
taken from RO and R1 as they exist when 
EXE$FINISHIO receives control 

EXE$FINISHIOC 

Finishes the I/O processing, returning a 
longword of status information to the caller 
of the QIO system service; the information 
is returned in the first longword of the IOSB 
specified in the call to QIO, and the status 
information is taken from RO as it exists 
when EXE$FINISFIIO receives control; the 
second longword of the IOSB is cleared 

EXE$QIODRVPKT 

Queues an IRP to the pending-l/O queue if 
the device is busy, or starts I/O activity if 
the device is idle 

RSB 

Returns control to the caller of the routine, 
that being the FDT-processing loop of the 
QIO system service 


1.2 The Start-I/O Routine 

The VAX/VMS routines IOC$REQCOM and IOC$INITIATE 
call a driver's start-I/O routine. The start-I/O routine activates 
the device. 

How to Specify This Entry Point 

Specify the name of the start-I/O routine as the START 
parameter to the DDTAB macro. This macro places the address 
of the routine into the DDT. 
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Inputs 


Register 

Contents 

R3 

The address of the IRP 

R5 

The address of the UCB 


VAX/VMS copies the following information from the current 
IRP into the UCB fields listed below. 


Field 

Contents 

UCB$W_BCNT 

The number of bytes to be transferred, 
copied from IRP$W_BCNT 


Note that only the low-order word is 
copied from the IRP; if the device 
supports transfers so large that the 
byte count must be expressed as a 
longword, the start-I/O routine must 
extract the count from the IRP and store 


it an an accessible place, such as the 
device-dependent UCB extension 

UCB$W_BOFF 

The offset from the beginning of its page 
of the first byte to be transferred, copied 
from IRP$W_BOFF 

UCB$L_SVAPTE 

The address of the page-table entry, 
copied from IRP$I SVAPTE 


Output 

The output of a start-I/O routine is device activity. 

Use of Registers 

The contents of all registers except RO, Rl, R2, and R4 must be 
preserved. 

If the start-I/O routine uses the stack, it must restore the stack 
before completing the request, waiting for an interrupt, or 
requesting system resources. 
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Context 


Start-I/O routines gain control of the processor in the context 
of a fork process. Consequently only addresses in nonpaged 
system memory are available to a start-I/O routine. 


I PL on Entry and Exit 


A start-I/O routine gains control of the processor, and 
relinquishes control, at fork IPL. For many devices, the start- 
I/O routine raises IPL to IPL$_POWER, power-fail IPL, in 
order to check that a power failure has not occurred on the 
device. The start-I/O routine initiates device activity at device 
IPL. 

Which VAX/VMS Routines Use This Entry Point 

IOC$INITIATE and IOC$REQCOM in module IOSUBNPAG 


1.3 The Interrupt-Servicing Routine 

The interrupt-servicing routine processes interrupts generated 
by the device. The interrupts can signal the completion of 
an I/O operation or an error. UNIBUS devices require an 
interrupt-servicing routine for each UNIBUS interrupt vector 
the device has. 

Tape devices on the MASSBUS require an interrupt-servicing 
routine that interrogates the tape formatter (the controller) to 
determine which drive needs attention and if the interrupt is 
unsolicited. 

Disk devices on the MASSBUS use an interrupt-servicing 
routine provided with VAX/VMS, and thus do not need to 
provide an interrupt-servicing routine. 

The functions performed by the interrupt-servicing routine are 
the following: 

1 Determine whether the interrupt was expected 

2 Process or dismiss unexpected interrupts 




1-5 










Device Driver Entry Points 


3 Activate the suspended driver so it can process expected 
interrupts 

For MASSBUS devices, the ISR supplied with VAX/VMS 
provides these functions. 

How to Specify This Entry Point 

Specify the name of the interrupt-servicing routine by using the 
DPT_STORE macro to place the address of the routine in the 
CRB, into the field CRB$L^_INTD+4. 

If the device has two different interrupts, use the DPT—STORE 
macro to specify the name of the second interrupt-servicing 
routine and to place the address of that routine into the 
longword field CRB$L__INTD2+4 within the CRB. 

Inputs 

When this routine is invoked, the stack contains the following: 


Stack Location 

Contents 

O(SP) 

The address of the longword that contains 
the address of the IDB 

4(SP) to 24(SP) 

For UNIBUS devices, the contents of RO 
through R5 at the time of the interrupt; for 
MASSBUS devices, only the contents of 

R2 through R5 are saved 

28(SP) 

PC at the time of the interrupt 

32(SP) 

PSL at the time of the interrupt 

Output 


Before dismissing an interrupt, this routine must remove the 
address of the pointer to the IDB from the top of the stack, and 
then restore RO through R5, which were saved by VAX/VMS 
when it dispatched the interrupt. Then this routine should end 
with an REI instruction. 

Before this routine transfers control to the suspended driver, it 
must restore the contents of R3 and R4 from the UCB. It must 
then transfer control to the address in UCB$L_FPC. 
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Use of Registers 

If the interrupt-servicing routine user R6 through Rll, the AP, 
or the FP, it must first save the contents of those registers, 
restoring their contents before exiting by means of the REI 
instruction. MASSBUS drivers must also preserve the contents 
of RO and Rl. 

Context 

The processor is running in kernel mode and is using the 
interrupt stack. The only addresses the routine can reference 
are addresses in nonpaged system memory. 

I PL on Entry and Exit 

This routine is called, executes, and returns at device IPL. 

Which VAX/VMS Routines Use This Entry Point 

This routine is called by the VAX/VMS interrupt-servicing 
routines, the addresses of which are usually loaded into the 
ADP, the CRB, or both for the interrupting device. 


1.4 The Cancel-I/O Routine 

This routine is called by VAX/VMS when the user calls the 
cancel-I/O system service to cancel all requests for I/O activity 
on a channel. It performs the following functions: 

• Determine whether an IRP associated with the cancellation 
request is actively being processed. It usually does so by 
first checking the bit UCB$V_BSY in the field UCB$W_STS 
to see if any request is being processed by the device. If so, 
the cancel-I/O routine tests whether the PID and channel 
number of the request being processed match the PID and 
channel number specified in the cancel-I/O request. 

• Cause to be completed (cancelled) as quickly as possible all 
active I/O requests on the specified channel that were made 
by the process that has requested the cancellation. 

The cancel-I/O routine usually accomplishes this by setting 
UCB$ V_C AN CEL in the field UCB$W_STS. When the next 
interrupt or timeout occurs for the device, the driver's start- 
I/O routine detects the presence of an active but cancelled 
I/O request by testing this bit and takes appropriate action. 
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such as completing the request without initiating any further 
device activity 


How to Specify This Entry Point 

Specify the name of the cancel-I/O routine as the CANCEL 
parameter to the DDTAB macro. This macro places the address 
of the routine into the DDT. 

Inputs 


Register 

Contents 

R2 

The channel's index number 

R3 

The address of the IRP being processed by the 
driver's start-l/O routine 

R4 

The address of the PCB of the process for which the 
I/O request is being cancelled 

R5 

The address of the device's UCB 

R8 

The code that stands for the caller of the cancel-I/O 
routine, one of the following: 


Code 

Meaning 

CAN$C_CANCEL 

The $CANCEL or $DALLOC 


system services 

CAN$C_DASSGN 

The SDASSGN system 


service 


Output 

The I/O requests on the specified channel are cancelled, and 
the bit UCB$V_CANCEL is set in the field UCB$L_STS. 

Use of Registers 

The driver's cancel-I/O routine can use RO through R3 freely. 
The contents of any other register must be restored before the 
cancel-I/O routine relinquishes control by means of an RSB 
instruction. 


1-8 










Device Driver Entry Points 


Context 

This routine executes in the context of the user's process, in 
kernel mode. 

I PL on Entry and Exit 

This routine is called at the fork IPL of the device. 

Which VAX/VMS Routines Use This Entry Point 

The $CANCEL, $DASSGN, and $DALLOC system services use 
this entry point from modules SYSCANCEL, SYSDASSGN, and 
SYSDEVALC, respectively. 


1.5 The Unsolicited-Interrupt-Handling Routine 

For MASSBUS disks, VAX/VMS calls the unsolicited-interrupt 
routine whenever a hardware event produces an interrupt that 
is not the result of a driver's request. Examples of such events 
are disks being placed on line or taken off line. 

Only drivers of MASSBUS disks must provide unsolicited- 
interrupt routines. All other devices detect unsolicited interrupts 
in their interrupt-servicing routines. 

The routine that handles these unsolicited interrupts must 
determine the nature of the interrupt and act accordingly, 
depending on the characteristics of the device and controller. 

How to Specify This Entry Point 

Provide the name of the unsolicited-interrupt routine as the 
UNSOLIC parameter to the DDTAB macro. This macro places 
the address of the routine into the driver-dispatch table. 

Inputs 


Register Contents 

R4 The address of the MASSBUS adapter's CSR 

R5 The address of the UCB 
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Output 

There are no required outputs. 

Use of Registers 

The unsolicited-interrupt-servicing routine must not alter the 
contents of registers R6 through Rll or the AP or FP. 

Context 


The processor is running in kernel mode and is using the 
interrupt stack. The only addresses the routine can reference 
are addresses in nonpaged system memory. 

I PL on Entry and Exit 

This routine is called, executes, and returns at device IPL. 


Which VAX/VMS Routines Use This Entry Point 

The MBA$INT routine in module MBAINTDSP of the SYSLOA 
facility calls this entry point. 


1.6 The Timeout-Handling Routine 

This routine handles the situation in which the device has not 
yet responded to a request for device activity and the time 
allowed for a response has expired. 

How to Specify This Entry Point 

Specify the name of the timeout-handling routine as an 
argument to the WFIKPCH or the WFIRLCH macro. 

Inputs 


Register Contents 


R3 

R4 

R5 


The contents of R3 when the last invocation of 
WFIKPCH or WFIRLCH took place 


The contents of R4 when the last invocation of 
WFIKPCH or WFIRLCH took place 

The address of the UCB of the device 
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Output 

There are no required outputs, but, depending on the 
characteristics of the device, the timeout-handling routine 
might cancel or retry the current I/O request, send a message 
to the operator, or take some other action. 

Before calling this routine, VAX/VMS places the device in 
a state in which no interrupt is expected (by clearing the 
bit UCB$V_INT in field UCB$W_STS). If the requested 
interrupt occurs after this routine is called, it will appear to 
be an unsolicited interrupt. Many drivers handle this situation 
by disabling interrupts while the timeout-handling routine 
executes. 

Use of Registers 

This routine can use RO through R2 freely. It must preserve the 
contents of all other registers. 

If this routine uses the stack, it must restore the stack before 
completing or cancelling the current I/O request, waiting for an 
interrupt, or returning control to its caller. 

Context 

This routine executes in the context of a fork process. The 
only addresses to which this routine can refer are those in the 
system's nonpaged memory. 

I PL on Entry and Exit 

This routine is called at device IPL. After taking whatever 
device-specific action that might be necessary at device IPL, this 
routine can lower IPL to fork IPL. 

Which VAX/VMS Routines Use This Entry Point 

The WFIKPCH and WFIRLCH macros use this entry point, but 
only when the name of this routine is provided as a parameter 
to those macros. These macros are used in the driver's start- 
I/O routine, thus, strictly speaking, the driver itself is the only 
entity that uses this entry point. 

Routines in the VAX/VMS module TIMESCHDL call this 
routine at the request of the WFIKPCH and WFIRLCH macros. 
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1.7 The Register-Dumping Routine 


The VAX/VMS error-logging and diagnostic-buffer-filling 
routines call this routine to copy the contents of the device's 
registers into the error-log entry or the diagnostic buffer. 

How to Specify This Entry Point 

Specify the name of the register-dumping routine as the 
REGDMP parameter to the DDTAB macro. This macro places 
the address of the routine into the DDT. 

Inputs 

The register-dumping routine has the following inputs. 


Register Contents 

RO The address of the buffer into which this 


routine is to copy the contents of the device's 
registers 

The address of the device's CSR 
The address of the UCB of the device 



R4 

R5 


Output 

The contents of the device's registers are copied into the 
buffer. 

Use of Registers 

This routine preserves the contents of all registers except RO 
through R2. If this routine uses the stack, it must restore the 
stack before passing control to another routine, waiting for an 
interrupt, or returning control to its caller. 

Context 

This routine executes within the context of an interrupt¬ 
servicing routine or a fork process, using the kernel-mode 
stack. It can refer only to addresses in the system's nonpaged 
memory. 
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I PL on Entry and Exit 

This routine is called at the same IPL at which the driver called 
the VAX/VMS routine ERL$DEVICERR, ERL$DEVICTMO, or 
IOC$DIAGBUFILL. It must not change IPL. 

Which VAX/VMS Routines Use This Entry Point 

The routines ERL$DEVICERR, ERL$DEVICTMO, in module 
ERRORLOG, and IOC$DIAGBUFILL, in module IOSUBNPAG, 
call this routine. 


1.8 The Alternate Start-I/O Routine 

The alternate start-I/O routine is an optional entry point. It 
is present only in drivers that in some circumstances initiate 
multiple, concurrent I/O activity on a device. Drivers that 
use an alternate start-I/O routine must perform their own 
synchronization of access to the UCB and thus to the device. 

How to Specify This Entry Point 

Specify the name of the alternate-start-I/O routine as the 
ALTSTART parameter to the DDTAB macro. This macro places 
the address of the routine into the DDT. 

Input 


Location 

Contents 

R3 

The address of the IRP 

R5 

The address of the UCB 


The alternate start-I/O routine is an optional entry point. It 
is present only in drivers that in some circumstances initiate 
multiple, concurrent I/O activity on a device. Drivers that 
use an alternate start-I/O routine must perform their own 
synchronization of access to the UCB and thus to the device. 

How to Specify This Entry Point 

Specify the name of the alternate-start-I/O routine as the 
ALTSTART parameter to the DDTAB macro. This macro places 
the address of the routine into the DDT. 
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Input 

This routine requires the same input as the start-I/O routine. 

Output 

The output of an alternate start-I/O routine is device activity. 

Use of Registers 

The contents of all registers except RO through R5 must be 
preserved. 

Context 

Start-I/O routines gain control of the processor in the context 
of a fork process. Consequently only addresses in the system's 
nonpaged memory, are available to an alternate start-I/O 
routine. 

I PL on Entry and Exit 

Alternate start-I/O routines are called at fork IPL. 

Which VAX/VMS Routines Use This Entry Point 

The routine EXE$ALTQUEPKT, in module SYSQIOREQ, calls 
this routine. 


1.9 The Controller-Initialization Routine 

Controller-initialization routines ready controllers for operation. 
If the controller requires it, a driver must initialize the controller 
when the system's driver-loading routine loads the driver and 
when the system is recovering from a power failure. 

How to Specify This Entry Point 

Specify the name of the controller-initialization routine by using 
the DPT—STORE macro to place the address of the routine in 
the CRB, into the field CRB$L_INTD+VEC$L_INITIAL. 
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Inputs 

The caller of controller-initialization routines provides the 
following information. 


Register Contents 

R4 The address of the CSR 

R5 The address of the IDB that describes the controller 

R6 The address fo the DDB associated with the 

controller 

R8 The address of the CRB for the controller 


The SYSGEN utility creates all the I/O data structures 
associated with a device before calling the controller- 
initialization routine. 

Output 

Depending on the device, controller-initialization routines do 
any or all of the following: 

• Clear error-status bits in device registers 

• Enable controller interrupts 

• Store values in fields that are offset more than 256 bytes 
from the beginning of the data structure and consequently 
cannot be reached with the DPT—STORE macro. 

• Allocate resources that must be permanently allocated to the 
controller. 

• If the controller is dedicated to a single-unit device, such 
as a printer, fill in IDB$L_OWNER and set the online bit 
(UCB$V_ONLINE in UCB$W_STS). 

Use of Registers 

Initialization routines must preserve the contents of all registers 
except RO through R2. If the controller-initialization routine 
uses these registers, it must save their contents first and then 
restore those contents before returning control to the caller. 
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Context 

Controller-initialization routines execute within system context. 
The only addresses these routines can reference are addresses 
in the system's nonpaged memory. 

I PL on Entry and Exit 

VAX/VMS calls controller-initialization routines at IPL$_ 
POWER. Controller-initialization routines must not lower IPL. 

Which VAX/VMS Routines Use This Entry Point 

SYSGEN calls this entry point when processing a CONNECT 
command. VAX/VMS calls this routine if the device, the 
controller, the processor, or the adapter to which the device is 
connected experiences a power failure. 


1.10 The Unit-Initialization Routine 

Unit-initialization routines ready for operation devices and, for 
devices on a dedicated controller, their controllers. A driver 
must initialize the device when the driver-loading routine loads 
the driver and when the system is recovering from a power 
failure. 

How to Specify This Entry Point 

You can specify this entry point in two ways. Either way 
will suffice for all but a few, specific devices. Drivers of 
MASSBUS disks specify this routine in the DDT. If you use 
both methods in the same driver, VAX/VMS chooses between 
the specifications randomly. 

You can use the DDTAB macro to specify the unit-initialization 
routine by providing the name of the routine as the argument 
to the UNITINIT keyword. 

You can use the DPT_STORE macro to place the address of 
the unit-initialization routine in the CRB, into field CRB$L_ 
INTD+VEC$L_UNITINIT. 
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Inputs 

The caller of unit-initialization routines provides the following 
information. 


Register 

Contents 

R3 

The address of the primary CSR 

R4 

The address of the secondary CSR, if it exists; if it 
does not, the contents of R4 are the same as those 
of R3 

R5 

Address of the UCB 


In addition, SYSGEN creates the I/O data structures associated 
with a device before calling the unit-initialization routine. 

Output 

Depending on the device, unit-initialization routines do any or 
all of the following: 

1 Clear error-status bits in device registers 

2 Enable controller interrupts 

3 Set the online bit (UCB$V_ONLINE in UCB$W_STS) 

4 Store values in fields that are offset more than 256 bytes 
from the beginning of the UCB and consequently cannot be 
reached with the DPT_STORE macro. 

5 Allocate resources that must be permanently allocated to the 
device or, for some devices, the controller. 

6 If the device has a dedicated controller, as, for example, 
some printers do, fill in IDB$L_OWNER. 

Use of Registers 

Initialization routines must preserve the contents of all registers 
except RO through R2. If the unit-initialization routine uses 
these registers, it must save their contents first and then restore 
those contents before returning control to the caller. 
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Context 

VAX/VMS calls unit-initialization routines within system 
context. The only addresses a unit-initialization routine can 
reference are those in the system's nonpaged memory. 

I PL on Entry and Exit 

VAX/VMS calls initialization routines at IPL$_POWER. Unit- 
initialization routines must not lower IPL. 

Which VAX/VMS Routines Use This Entry Point 

The SYSGEN utility calls this entry point when processing 
a CONNECT command. VAX/VMS calls this routine if the 
device, the controller, the processor, or the adapter to which the 
device is connected experiences a power failure and restoration. 


1.11 The Unit-Delivery Routine 

For controllers that can control a variable number of device 
units, the unit-delivery routine determines which specific 
devices are present and available for inclusion in the system's 
configuration. 

SYSGEN calls the unit-delivery routine once for each unit the 
controller is capable of controlling, a total of DEFUNITS times, 
where DEFUNITS is specified by the DEFUNITS parameter to 
the DPTAB macro. 

How to Specify This Entry Point 

Specify the name of the unit-delivery routine as the DELIVER 
parameter to the DPTAB macro. 
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Inputs 


Register 

Contents 

R3 

The address of the controller's IDB; 0 if no IDB exists 

R4 

The address of the CSR 

R5 

The number of the unit that this routine must decide 
to configure or not to configure 

R6 

The address of the start of the UNIBUS adapter's I/O 
space 

R7 

The address of the AUTOCONFIGURE command's 
ACF 

R8 

The address of the UNIBUS's ADP 


Output 

If bit 0 is set in RO, the unit should be configured; if it is 
cleared, the unit should not be configured. 

Use of Registers 

This routine can use RO through R2 freely. It must preserve the 
contents of all other registers. 

Context 

This routine executes in the context of the process within which 
SYSGEN executes. 

I PL on Entry and Exit 

This routine is called at IPL$_POWER, IPL 31. This routine 
must not lower IPL. 

Which VAX/VMS Routines Use This Entry Point 

SYSGEN's AUTOCONFIGURE command calls this routine. 
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ACP: See ancillary control process. 

adapter-control block (ADP): A structure in the I/O database that 
describes either a UNIBUS or MASSBUS adapter. 

ADP: See adapter-control block. 

allocate a device: To reserve a particular device unit for exclusive use. 
A user process can allocate a device only when that device is not 
allocated by any other process. 

ancillary control process (ACP): A process that acts as an interface 
between user software and an I/O driver. An ACP provides 
functions supplemental to those performed in the driver, such as 
file and directory management. 

Three examples of ACPs are the Files-11 ACP (FI 1 ACP), the 
magnetic tape ACP (MTAACP), and the networks ACP (NETACP). 

assign a channel: To establish the necessary software linkage 

between a user process and a device unit before a user process can 
communicate with that device. A user process requests the system to 
assign a channel and the system returns a channel number. 

AST: See asynchronous system trap. 

ASTLVL: See asynchronous system trap level. 

asynchronous system trap (AST): A software-simulated interrupt 
that passes control to a user-defined routine. ASTs enable a user 
process to be notified asynchronously, with respect to the execution 
of the user process, of the occurrence of a specific event. 

If a user process has defined an AST routine for an event, the system 
interrupts the process and executes the AST routine when that event 
occurs. When the AST routine exits, the system resumes execution of 
the process at the point where it was interrupted. 
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asynchronous system trap level (ASTLVL): A value kept in an 
internal processor register that is the highest access mode for which 
an AST is pending. The AST does not occur until the current access 
mode drops in privilege (rises in numeric value) to a value greater 
than or equal to ASTLVL. Thus an AST for an access mode will not 
be serviced while the processor is executing in a more privileged 
access mode. 

backplane interconnect: An internal processor bus that UNIBUS 
and MASSBUS adapters use to communicate with main memory 
and the central processor. The backplane interconnect is called 
the synchronous backplane interconnect (SBI) on the VAX-11/780 
processor, and is called the memory interconnect on the VAX-11 
/750 processor. 

base register: A general register used to contain the base address of 
(the address of the first entry in) a list, table, array, or other data 
structure. 

buffered data path: A UNIBUS adapter data path that transfers 
several bytes of data in a single backplane-interconnect transfer. 

buffered I/O: See system buffered I/O. 

bugcheck: The operating system's internal diagnostic check. The 
system logs the failure and crashes the system. 

CALL instructions: The processor instructions CALLG (Call Procedure 
with General Argument List) and CALLS (Call Procedure with Stack 
Argument List). 

CCB: See channel-control block. 

channel: A logical path connecting a user process to a physical device 
unit. A user process requests the operating system to assign a 
channel to a device so the process can communicate with that device. 
See also controller data channel. 

channel-control block (CCB): A structure in the I/O database 
maintained by the Assign-I/O-Channel system service to describe 
the device unit to which a channel is assigned. 
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channel-request block (CRB): A structure in the I/O database that 
describes the activity on a particular controller. The channel-request 
block for a controller contains pointers to the queue of drivers 
waiting to access a device through the controller. 

configuration register: A control/status register for an adapter, for 
example a UNIBUS adapter. It resides in the adapter's I/O space. 

connect-to-interrupt: A function by which a process connects to 
a device interrupt vector. To perform a connect-to-interrupt, the 
process must map to the program I/O space containing the vector. 

console: The manual control unit integrated into the central processor. 
The console includes a serial-line interface connected to a hard-copy 
terminal. This enables the operator to start and stop the system, 
monitor system operation, and run diagnostic programs. 

console terminal: The hard-copy terminal connected to the central 
processor's console. 

context: The environment of an activity. See also process context, 
hardware context, and software context. 

controller data channel: A logical path, access to which the driver of 
a device that shares a controller must gain access before it can use 
the controller to activate a device. 

control/status register (CSR): A control/status register for a device 
or controller. It resides in the processor's I/O space. 

CRB: See channel-request block. 

CSR: See control/status register. 

database: A collection of related data structures; all the occurrences of 
data described by a database management system. 

data structure: Any table, list, array, queue, or tree whose format and 
access conventions are well-defined for reference by one or more 
images. 

DDB: See device-data block. 

DDT: See driver-dispatch table. 
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device-data block (DDB): A structure in the I/O database that 
identifies the generic device/controller name and driver name for 
a set of devices that share the same controller. 

device interrupt: An interrupt received on interrupt priority levels 
20 through 23. Device interrupts can be requested only by devices, 
controllers, and memories. 

device register: A location in controller logic used to request device 
functions (such as I/O transfers) and/or report status. 

device unit: One drive and its controlling logic, for example, a 
disk drive or terminal. Some controllers can have several device 
units connected to a single controller, mass-storage controllers, for 
example. 

diagnostic program: A program that tests hardware, firmware, 
peripherals logic, or memory, and that reports any faults it detects. 

direct data-path: A UNIBUS adapter's data path that transfers several 
bytes of data in a single backplane-interconnect transfer. 

direct I/O: An I/O operation in which VAX/VMS locks the pages 
containing the associated buffer in physical memory for the duration 
of the I/O operation. The I/O transfer takes place directly from the 
process's buffer. Contrast with system buffered I/O. 

DPT: See driver-prologue table. 

drive: The electromechanical unit of a mass storage device on which a 
recording medium (disk cartridge, disk pack, or magnetic tape reel) is 
mounted. 

driver: The set of instructions and tables that handles physical I/O 
operations to a device. 

driver-dispatch table (DDT): A table in the I/O driver that lists the 
addresses of the entry points of standard driver routines and the 
sizes of diagnostic and error-logging buffers for the device. 

driver-prologue table (DPT): A table in the driver that describes the 
driver and the type of device it drives to the VAX/VMS procedure 
that loads drivers into the system. 

ECC: Error-Correction Code. 
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error logger: A system process that empties the error-log buffers and 
writes the error messages into the error file. Errors logged by the 
system include memory errors, device errors and timeouts, and 
interrupts with invalid vector addresses. 

exception: An event detected by the hardware or software (other than 
an interrupt or jump, branch, case, or call instruction) that changes 
the normal flow of instruction execution. 

An exception is always caused by the execution of an instruction or 
set of instructions (whereas an interrupt is caused by an activity in 
the system that is independent of the current instruction). 

There are three types of hardware exceptions: traps, faults, and 
abortions. Examples are: attempts to execute a privileged or reserved 
instruction; trace traps; compatibility-mode faults, execution of 
breakpoint instructions; and arithmetic traps. 

executive: The software that provides the basic control and monitoring 
functions of the operating system. 

FDT: See function-decision table. 

FDT routines: Driver routines called by the Queue-I/O-Request system 
service to perform device-dependent preprocessing of an I/O request. 

fork block: That portion of a unit-control block that contains a driver's 
context while the driver is waiting for a resource. A driver awaiting 
the processor resource has its fork block linked into the fork queue. 

fork dispatcher: A VAX/VMS interrupt-servicing routine that is 
activated by a software interrupt at a fork-interrupt priority level. 
Once activated, it dispatches driver fork processes from a driver-fork 
queue until no processes remain in the queue for that IPL. 

fork process: A process with a minimal context that executes 

instructions under a set of constraints: it executes at raised interrupt 
priority levels; it uses RO through R5 only (other registers must be 
saved and restored); it executes in the system's virtual address space; 
it can refer to and modify static storage that is never modified by 
procedures that execute at a higher IPL. VAX/VMS uses software 
interrupts and fork processes to synchronize executive operations. 
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fork queue: A queue of fork blocks that are awaiting activation at a 
particular IPL by the VAX/VMS fork dispatcher. 

function code: See 1/O-function code. 

function-decision table (FDT): A table in the driver that lists all valid 
function codes for the device, and lists the addresses of preprocessing 
routines associated with each valid function of the device. 

function modifier: See 1/O-function modifier. 

generic device name: A device name that identifies the type of 
device but not a particular unit; a device name in which the specific 
controller and/or unit number is omitted. When discussing device 
drivers, the generic device name contains neither the controller 
designation nor the unit number, for example, DB. 

hardware context: The values contained in the following registers 
while a process is executing: 

• The PC 

• The PSL 

• The 14 general registers (RO through R13) 

• The four processor registers (POBR, POLR, P1BR and P1LR) that 
describe the process's virtual address space 

• The SP for the access mode in which the processor is executing 

• The contents to be loaded in the SP for every access mode other 
than the current access mode. 

When a process is executing, its hardware context is continually 
being updated by the processor. When a process is not executing, its 
hardware context is stored in its hardware PCB. 

hardware process-control block (hardware PCB): A data structure 
known to the processor that contains the hardware context when 
a process is not executing. A process's hardware PCB resides in its 
process header (PHD). 

IDB: See interrupt-dispatch block. 
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interrupt: An event other than an exception or a branch, jump, case, or 
call instruction that changes the normal flow of instruction execution. 
Interrupts are generally external to the process executing when the 
interrupt occurs. See also device interrupt, software interrupt , and 
urgent interrupt. 

interrupt-dispatch block (IDB): A structure in the I/O database that 
describes the characteristics of a particular controller and points to 
devices attached to that controller. 

interrupt priority level (IPL): The level at which a software or 
hardware interrupt is generated. There are 32 interrupt priority 
levels: IPL 0 is lowest, 31 is highest. The levels arbitrate contention 
for processor service. For example, a device cannot interrupt the 
processor if the processor is currently executing at an interrupt 
priority level greater than the interrupt priority level of the device's 
interrupt-servicing routine. 

interrupt-servicing routine (ISR): A routine executed when a device 
interrupt occurs. 

interrupt stack (IS): The system-wide stack used when executing 
instructions in interrupt context. At any time, the processor is either 
in a process context, executing in user, supervisor, executive, or 
kernel mode, or in system-wide, interrupt context, operating in 
kernel mode, as indicated by the interrupt stack and current-mode 
bits in the PSL. Context-switching does not take place when the 
system is using the interrupt stack. 

interrupt-stack pointer (ISP): The pointer to the top of the interrupt 
stack. Unlike the stack pointers for process context stacks, which are 
stored in the hardware PCB, the interrupt-stack pointer is stored in 
an internal processor register. 

interrupt vector: See vector. 

I/O database: A collection of data structures that describes I/O 
requests, controllers, device units, volumes, and device drivers in 
a VAX/VMS system. Examples are the driver-dispatch table, driver- 
prologue table, device-data table, unit-control block, channel-request 
block, I/O-request packet, and interrupt-data block. 

I/O driver: See driver. 
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I/O function: An I/O operation interpreted by the operating system 
and typically resulting in one or more physical I/O operations. 

l/O-function code: A 6-bit value specified in a Queue-I/O-Request 
system service that describes the particular I/O operation to be 
performed (such as, read, write, rewind). 

l/O-function modifier: A 10-bit value specified in a Queue-I/O- 
Request system service that modifies an I/O-function code (for 
example: read terminal input, no echo). 

I/O lockdown: The state of a page such that it cannot be paged or 
swapped out of memory. 

l/O-request packet (IRP): A structure in the I/O database that 
describes an individual I/O request. The Queue-I/O-Request 
system service creates an I/O-request packet for each I/O request. 
VAX/VMS and the driver of the target device use information in the 
I/O-request packet to process the request. 

I/O rundown: An operating system function in which the system 
cleans up any I/O in progress when an image exits. 

I/O space: The regions of physical address space that contain the 
configuration registers, and device control/status and data registers. 
These regions are physically discontiguous. 

l/O-status block (IOSB): A data structure associated with the Queue- 
I/O-Request system service. This service optionally returns a status 
code, number of bytes transferred, and device/function-dependent 
information in an I/O-status block. The information returned is not 
returned from the system service call, but filled in by VAX/VMS 
when the I/O request completes. 

I PL: See interrupt priority level. 

IRP: See I/O-request packet. 

ISP: See interrupt-stack pointer. 

ISR: See interrupt-servicing routine. 
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limit: The size or number of items requiring system resources (such as 
mailboxes, locked pages, I/O requests, or open files) that a job is 
allowed to have at any one time during execution, as specified by the 
system manager in the user-authorization file. See quota. 

locking a page in memory: Making a page in an image ineligible for 
either paging or swapping. A page stays locked in physical memory 
until VAX/VMS specifically unlocks it. 

logical-I/O function: A set of I/O operations (for example, read- 
logical-block and write-logical-block) that allow restricted direct 
access to device-level I/O operations using logical block numbers. 

mailbox: A software data structure that is treated as a record-oriented 
device for interprocess communication. Communication using a 
mailbox is similar to other forms of device-independent I/O. Senders 
write to a mailbox; the receiver reads from that mailbox. Examples: 
the error logger and OPCOM read from system-wide mailboxes. 

MASSBUS adapter (MBA): An interface device between the 
backplane interconnect and the MASSBUS. 

memory interconnect: The internal processor bus for the 
VAX-11/750. 

offset: A displacement from the beginning of a data structure to the 
beginning of a field within that data structure. Offsets for items 
within a data structure usually have an associated symbol. The name 
of the symbol is used to refer to the field; its value is the offset. 

page-frame number (PFN): The high-order 21 bits of the physical 
address of a page in physical memory. 

page-table entry (PTE): The data structure that identifies the physical 
location and status of a page of virtual address space. When a 
virtual page is in memory, the PTE contains the page-frame number 
needed to map the virtual page to a physical page. When it is not 
in memory, the page-table entry contains the information needed to 
locate the page on secondary storage (disk). 

PCB: See Process-Control Block. 

PFN: See page-frame number. 
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physical address: The address used by hardware to identify a location 
in physical memory or on directly-addressable secondary storage 
devices such as disks. A physical-memory address consists of a 
page-frame number and the number of a byte within the page. A 
physical-disk-block address consists of a cylinder or track and a 
sector number. 

physical address space: The set of all possible physical addresses 
that can be used to refer to locations in memory (memory space) or 
device registers (I/O space). 

physical-l/O functions: A set of I/O functions that allows access to 
all device-level I/O operations except maintenance-mode operations. 

PID: See process identification. 

process: The basic entity, scheduled by the system software, that 
provides the context in which an image executes. A process consists 
of an address space, hardware context, and software context. 

process context: The hardware and software contexts of a process. 

process-control block (PCB): A data structure used to contain process 
context. The hardware PCB contains the hardware context. The 
software PCB contains the software context, which includes a pointer 
to the hardware PCB. 

process identification (PID): A 32-bit value that uniquely identifies a 
process. Each process has a PID and a name. 

process I/O channel: See channel. 

process page tables: The page tables used to describe process virtual 
memory. 

process priority: The priority assigned to a process for scheduling 
purposes. The operating system recognizes 32 levels of process 
priority, where 0 is low and 31 high. Levels 16 through 31 are used 
for real-time processes. The system does not modify the priority 
of a real-time process (although the system manager or the process 
itself might). Levels 0 through 15 are used for normal processes. 

The system can temporarily increase the priority of a normal process 
based on the activity of the process. 

Contrast with interrupt priority level. 
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program section: A portion of a program with a given protection and 
set of storage-management attributes. Program sections that have the 
same attributes are gathered together by the linker to form an image 
section. 

PTE: See page-table entry. 

QIO: Queue-I/O-Request system service. The VAX/VMS system 
service that services $QIO and $QIOW requests. The Queue-I/O- 
Request system service prepares an I/O request for processing by the 
driver and performs device-independent preprocessing of the request. 
This system service also calls driver FDT routines. 

quota: The total amount of a system resource, such as CPU time, that 
a job is allowed to use in an accounting period, as specified by the 
system manager in the user-authorization file. See limit. 

return status code: See status code. 

SBI: See Synchronous Backplane Interconnect. 

small process: A system process that has no control region in its 
virtual address space and has an abbreviated context. Examples are 
the swapper and the null process. A small process is scheduled in 
the same manner as user processes, but must remain resident until it 
completes execution; it cannot be swapped. 

software context: The context maintained by VAX/VMS to describe a 
process. See also software process-control block (PCB). 

software interrupt: An interrupt generated on interrupt priority level 
1 through 15 that can be requested by software. 

software process-control block (software PCB): The data structure 
used to contain a process's software context. The operating system 
defines a software PCB for every process when the process is created. 

The software PCB includes the following kinds of information about 
the process: current state; storage address, if the process is swapped 
out of memory; unique identification of the process; and address of 
the process header (which contains the hardware PCB). The software 
PCB resides in system region of virtual address space. It is not 
swapped with a process. 
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start-I/O routine: The routine in a device driver that is responsible for 
obtaining needed resources and for activating the device unit. An 
example of a needed resource is the controller's data channel. 

status code: A longword value that indicates the success or failure 
of a specific function. For example, system services always return a 
status code in RO upon completion. 

SVA: See system virtual address. 

Synchronous Backplane Interconnect (SBI): The part of the 
VAX-11/780 hardware that interconnects the processor, memory 
controllers, MASSBUS adapters, the UNIBUS adapter. 

system buffered I/O: An I/O operation, such as terminal or mailbox 
I/O, in which an intermediate buffer from the system's buffer pool is 
used instead of a buffer in process space. See also direct I/O. 

System Page Table (SPT): The data structure that maps the system 
virtual addresses, including the addresses used to refer to the process 
page tables. The SPT contains one PTE for each page of system 
virtual memory. The physical base address of the SPT is contained 
in a processor register called SBR. 

system virtual address (SVA): A virtual address identifying a 
location mapped to an address in system space. 

timeout: The expiration of the time limit in which a device is to 
complete an I/O transfer. The driver's wait-for-interrupt request 
specifies the timeout limit. 

timer: A system process that maintains the time of day and the date. 

It is also alert for device timeouts and performs time-dependent 
scheduling upon request. The timer's interrupt-servicing routine 
creates the timer process. 

UCB: See unit-control block. 

UNIBUS adapter: An interface device between the backplane 
interconnect and the UNIBUS. On the VAX-11/780, this device 
is called the UBA. On the VAX-11/750, it is called the UBI. 
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unit-control block (UCB): A structure in the I/O database that 
describes the characteristics of a device unit and current activity 
on it. The unit-control block also holds the fork block for its unit's 
device driver; the fork block is part of the UCB and is a critical part 
of a driver fork process. The UCB also provides a static storage area 
for the driver. 

unit-initialization routine: The routine that readies controllers and 
device units for operation. Controllers and device units require 
initialization after a power failure and during execution of the 
driver-loading procedure. 

urgent interrupt: An interrupt received on interrupt priority levels 24 
through 31. These can be generated only by the processor for the 
interval clock, serious errors, and power failures. 

vector: A one-dimensional array. 

An interrupt or exception vector is a storage location known to the 
system that contains the starting address of a routine to be executed 
when a given interrupt or exception occurs. The system defines 
separate vectors for each interrupting adapter and for classes of 
exceptions. Each system vector is a longword. 

For the purpose of handling exceptions, users can declare up to two 
software-exception vectors (primary and secondary) for each of the 
four processor-access modes. Each vector contains the address of a 
condition handler, and is a longword. 

virtual-l/O functions: A set of I/O functions that must be interpreted 
by an ancillary control process. 

wait-for-interrupt request: A request made by a driver's start-I/O 
routine after it activates a device. The request causes the driver's fork 
process to be suspended until the device requests an interrupt or the 
device times out. 

XDELTA: A tool for debugging operating systems and drivers. 
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ACB$V_QUOT A • 8-19 
Access violation *8-13 
ACF (Configuration-control block) *A-2 
ACF$B_AFLAG • A-3 
ACF$B_AUNIT • A-3 
ACF$B_COMBO_CSR • A-4 
ACF$B_COMBO_VEC • A-4 
ACF$B_CUNIT • A-3 
ACF$B_NUMUNIT • A-4 
ACF$B_NUMVEC • A-4 

ACF$I_ADAPTER • A-3 

ACF$I_CONFIGREG • A-3 

ACF$I_CONTROLREG • A-3 

ACF$I_DEVNAME • A-3 

ACF$l_DLVR—SCRH • A-4 

ACF$I_DRVNAME • A-3 

ACF$V_CRBBLT • A-3 
ACF$V_GETDONE • A-3 
ACF$ V_NOLO AD_DB • A-3 
ACF$ V_RELO AD • A-3 
ACF$V_SCBVEC • A-3 
ACF$V_SUPPORT • A-3 
ACF$W_A VECTOR • A-3 
ACF$ W-CVECTOR • A-3 
ACF$W_M AXUNITS • A-4 
Activating the device • 9-7 
Adapter 

nexus values 

displaying* 14-10 
type 

specifying • 7-4 
Adapter-control block* 10-1 
Address resolution • 7-8 
ADP* 10-1 

ADP (adapter-control block)* 1-10 
ADP$B_NUMBER • A-6 
ADP$B_TYPE • A-6 

ADP$I_A VECTOR • A-8 

ADP$I_BLONLY • A-8 

ADP$I_CSR • A-6 

ADP$I_DPQBL • A-8 

ADP$I_DPQFL • A-7 


ADP$I_INTD • A-8 

ADP$I_LINK • A-6 

ADP$I_MRACTMDRS • A-9 

ADP$L_MRQBL* A-8 

ADP$I_MRQFL • A-8 

ADP$I_UBASCB • A-8 

ADP$I_UCBSPTE • A-9 

ADP$I_VECTOR • A-7 

ADP$W_ADPTYPE • A-6 
ADP$W_DPBITMAP • A-9 
ADP$W_MRFFENCE • A-9 
ADP$ W_MRFREG ARY • A-10 
ADP$W_MRNFENCE • A-9 
ADP$W_MRNREGARY • A-9 
ADP$W_SIZE • A-6 
ADP$W_TR* A-6 
ADP$ W_UMR_DIS • A-10 
Alternate start-l/0 routine *1-13 

ARB$I_UIC • A-39 

ARB$Q_PRIV • A-39 
$ASSIGN • 5-2, 7-10 
AST *8-13, 8-19 

kernel-mode *5-22, 8-10 
user-mode* 5-23 
Asynchronous system trap 
See AST 
Asynchrony* 1-4 
At-sign character*7-7 
AUTOCONFIGURE command *7-5 


B 


Backplane interconnect* 1-2, 1-20 
Branching instructions • 6-2 
Buffer deallocation *3-11 
Buffered data path *4-4, 4-7 
Buffered 1/0*7-14 

buffer deallocation • 8-10 
overhead *7-14 
postprocessing *8-10 
writing operation • 8-9 
Buffered-read-function bit • 13-6 
Busy device*8-23 
Byte-offset bit *4-10, 10-7, 10-8 
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Cancel-I/O bit* 12-9, 13-8 
Cancel-I/O request* 12-8 
Cancel-I/O routine* 1-3, 1-17, 7-9, 1-8 
circumstances in which VAX/VMS 
calls a* 13-5 
codes* 13-7 
device-dependent* 13-8 
device-independent* 13-8 
drivers that do not need a* 13-7 
execution context • 13-6 
$CANDEF macro* 13-7 
Card-reader driver* 11-8 
CASE macro *B-2 

CCB (channel-control block)* 1-10, 5-4 
CFCB • 14-22 
CFVB • 14-21 
Channel *3-24 
keeping *9-8 
releasing *9-8 

Channel-arbitration routine *3-26 
Channel-control block 
See CCB 

Channel-index number*5-2, 13-8 
Channel-request block *5-4, 10-3, 

13-3 
See CRB 

Channel-wait queue *9-3 
+ character* 7-10 
@ character*7-7 
CMEXEC privilege* 14-2 
CMKRNL privilege* 14-2 
Code 

l/0-function*9-5 
COMSDELATTN AST • C-2 
COM$DRVDE ALMEM • C-3 
COM$FLUSH ATTNS • C-4 
COM$POST • 8-24, C-5 
COM$SET ATTN AST • C-6 
Configuration 

automatic* 14-13 

driver control of* 14-20 
displaying information about* 14-11 
how many units to include in the* 
14-20 

rules for* 14-22 
UNIBUS example* 14-23 


Configuration-control block 
See ACF 

Control blocks* 1-7 
Control mask *9-6 
Controller 

access to*9-3 
data channel *9-3, 9-8 
releasing* 12-3 

dedicated *3-24, 5-6, 11-8, 12-3 
enabling interrupts on* 13-1 
initialization • 14-7 
maximum units attached to a* 14-7 
multiunit • 5-6 

number of units created for a *7-5 
number of units supported by a* 
7-5 

obtaining control of a MASSBUS* 
G-8 

shared *3-24 
with several devices *9-3 
with single device *9-3 
Controller interrupt 
enabling* 13-1 

Controller-initialization routine • 9-5, 
13-3, 14-10, 1-14 
address of • 7-3 
input* 13-4 

CRB (channel-request block)* 1-9, 3-5, 
5-4, 5-6, 10-3, 10-4, 13-3 
creation • 14-7 
CRB address*3-6 
CRB$B_M ASK • A-13 
CRB$B_TT_TYPE • A-13 
CRB$B_TYPE • A-13 

CRB$l_AUXSTRUC • A-14 

CRB$I_DUETIME • A-14 

CRB$L_INTD* 11-2, A-14 

CRB$I_INTD2 • A-15 

CRB$l_INTD2+4 • A-27 

CRB$I_INTD+2 • 1 1-2 

CRB$l_INTD+4 • 7-3, A-27 

CRB$I_INTD+VEC$B_DAT AP • 10-12 

CRB$I_INTD+VEC$B_DAT APATH • 

10-3 

CRB$l_INTD+VEC$B_NUMREG • 10-6 

CRB$I_INTD+VEC$I_INITIAL* 7-3, 

13-3, 14-7 

CRB$l_INTD+VEC$I_UNITINIT • 14-8 
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CRBSl_INTD+VEC$W_MAPREG • 9-6, 

10-6 

CRBSl_LINK • A-14 

CRB$I_TIMELINK • A-14 

CRB$L_T OUTROUT • A-14 

CRBSl_WQBL • A-13 

CRBSl_WQFL • A-13 

CRB$ W_REFC • A-13 
CRB$ W_SIZE • A-13 

CRBI_INTD+VECSl_UNITINIT • 7-3 

CSR address*5-18 
locating • 10-10 

Current floating-vector base* 14-21 


D 


Data channel *9-3, 9-8 
Data path *4-3, 10-1 
available* 10-3 
buffered 

allocating* 10-1, 10-2 
allocating permanently* 10-3 
deallocating *10-1 
purging* 10-1, 10-2 
requesting • 10-2 
direct* 10-4 
limiting allocation* 10-4 
number *4-5, 10-3 
number 0*4-5, 10-4 
selecting* 10-4 
purging • 10-4, 10-11 
releasing* 10-2, 10-12 
unavailable* 10-3 
Data transfer 

backplane-interconnect* 1-20 
buffered-l/O* 1-22 
byte-aligned *4-10 
byte-count 

saving the* 12-4 
byte-offset *4-10, 10-4 
completing* 10-2 
computing length *9-6 
computing the starting address* 
10-8 

direct-l/O • 1-22 

direct-memory-access* 1-22, 10-1 
DMA* 1-22, 4-2, 4-5, 10-1 
on the Q-bus* D-1 
losing last byte of *9-6 


Data transfer (cont'd.) 
non-DMA 

on the Q-bus*D-1 
odd byte-count • 9-6 
overlapped • 9-3 
PIO* 1-21 

programmed-l/O* 1-21 
speed of *4-4, 4-6, 4-11 
starting address *9-6 
that require data manipulation • 7-14 
UNIBUS* 1-20 
word-aligned *4-10 
Data-path error* 10-12 
Data-path purge *4-10 
Data-path wait* 10-4 
Data-path-wait queue* 10-3, 10-12 
DC$_CARD • A-51 
DC$_DISK • A-51 
DC$_LP • A-51 
DCS—MAILBOX • A-51 
DC$_REALTIME • A-51 
DC$_SCOM • A-51 
DC$_T APE • A-51 
DC$_TERM • A-51 

DDB (device-data block)* 1-9, 5-4, 5-7 
creation* 14-7 
DDB$B_TYPE • A-20 
DDB$K_CART • A-21 
DDB$K_PACK • A-21 
DDB$K_SLOW • A-21 
DDB$K_T APE • A-21 

DDB$I_2P_UCB • A-21 

DDB$I_ACPD • A-21 

DDB$I_ALLOCLS • A-21 

DDB$I_CONLINK • A-21 

DDB$I_DDT • 7-3, A-20, A-27 

DDB$I_LINK • A-20 

DDB$I_SB • A-21 

DDB$I_UCB • A-20 

DDB$T_DRVNAME • A-21 
DDB$T_NAME • A-21 
DDB$W_SIZE • A-20 
DDT (driver-dispatch block) *7-1 
address of • 7-3 

DDT (driver-dispatch table)* 1-3, 7-8 

DDT$I_ALTSTART *8-24, A-24 

DDT$I_CANCEL* A-23 

DDT$I_CLONEDUCB • A-24 

DDT$I_FDT • A-23 

DDT$I_MNTV_FOR • A-24 
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DDT$l_MNTV_SQD • A-24 

DDT$I_MNTV_SSSC • A-24 

DDT$I_MNTVER • A-24 

DDT$I_REGDUMP • A-23 

DDT$I_START • A-22 

DDT$I_UNITINIT • 13-3, 14-8, A-24 

DDT$I_UNSOLINT • A-22 

DDT$W_DI AGBUF • A-23 
DDT$W_ERRORBUF • 13-10, A-24 
DDT$W_FDTSIZE • A-24 
DDTAB macro *7-8, B-3 
CANCEL argument* 13-7 
REGDMP argument* 13-9 
Dedicated controller• 3-24, 5-6, 11-8, 
12-3 

$DEF macro *B-7 
$DEFEND macro *B-8 
SDEFINI macro *B-9 
DEV$V_2P • A-50 
DEV$V_ALL* A-48 
DEV$ V_A VL • A-48 
DEV$V_CCL* A-47 
DEV$ V_CDP • A-50 
DEV$V_CLU • A-50 
DEV$ V_DET • A-50 
DEVS V_DIR • A-47 
DEV$V_DMT • A-48 
DEVS V_DU A • A-48 
DEV$V_ELG* 13-10, A-48 
DEV$V_FOD • A-48 
DEV$V_FOR • A-48 
DEV$V_GEN • A-48 
DEV$V_IDV • A-49 
DEV$V_MBX • A-48 
DEV$V_MNT • A-48 
DEV$V_MSCP • A-50 
DEV$V_NET • A-48 
DEV$V_NNM • A-50 
DEVS V_ODV • A-49 
DEVS V_OPR • A-48 
DEV$V_RCK • A-49 
DEV$V_RCT • A-48 
DEV$V_REC • A-47 
DE V$V_RED • A-50 
DEVS V_RND • A-49 
DEV$V_RTM • A-49 
DEV$V_RTT* A-50 
DEV$V_SDI • A-48 
DEV$V_SHR* A-48 
DE V$ V_SPL • A-48 


DEVS V_SQD • A-48 
DEV$V_SRV • A-50 
DEV$V_SSM • A-50 
DEV$ V_SWL • A-48 
DEV$V_TRM • A-47 
DEV$V_WCK • A-49 
Device 

activating • 2-6, 4-2, 9-3, 9-6, 9-7, 
10-2 

bit-mask for activating • 9-6 
busy• 8-23 
control mask*9-6 
control/status register *9-6 
CSR • 9-6 
DMA *4-2 
DR32 • 14-10 
error* 13-9 
file-structured • 2-4 
initialization *11-4 
interrupt* 1-12, 3-12, 9-8 
dismissing* 5-20 
expected *9-10 
IPL* 1-11, 3-2 
name *7-9, 14-4 
non-DIGITAL* 14-20, 14-23 
register* 1-2 

referring to • 6-4 
using • 6-4 

sharing a controller*9-8 
timeout* 1-16, 9-8, 9-11, 12-1, 
12-5, 13-9 
logging* 12-7 
UNIBUS* 14-7 

unit number on a MASSBUS* 14-6 
with dedicated controller*9-8 
word-aligned* 10-4 
Device IPL *3-12 
Device-activation bit-mask *9-6 
Device-busy bit* 13-8 
Device-data block *5-4, 5-7 
See DDB 

Device-dependent data 
storing • 7-4 

Device-dependent status 
saving the* 12-4 

Device-independent I/O processing* 
5-22 

Device-independent processing* 1-6 
Device-specific processing* 1-6 
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Device-timeout bit* 12-5 
Device-timeout handler* 1-16 
Diagnostic buffer *7-9, 8-22 
Direct data path* 1-20, 4-3, 4-6 
Direct I/O • 8-24 
Direct memory access 
See DMA 

Direct-vector UNIBUS adaptor* 1-2 
Disk 

seek operation • 9-3 
Displacement-mode addressing *6-2 
DMA (direct-memory access)* 1-20 
DMA devices *7-14 
DMA 1/0*7-14 

DPT (Driver-prologue table)* 1-3, 1-23, 
7-1, 7-2 

initialization* 13-2 
DPT$B_ADPTYPE • A-26 
DPT$B_FLAGS• A-26 
DPT$B_REFC* A-26 
DPT$B_TYPE• A-26 

DPT$I_BLINK • A-25 

DPT$I_ECOLEVEL • A-29 

DPT$I_FLINK • A-25 

DPT$M_NOUNLOAD • 7-4, 14-9, A-26 
DPT$M_SUBCNTRL* A-26 
DPT$M_SVP • 7-4, A-26 
DPT$Q_LINKTIME • A-29 
DPT$T_NAME* 14-7, A-28 
DPT$V_SCS • A-26 
DPT$W_DEFUNITS* 14-20, A-28 
DPT$W_DELIVER* 14-20, A-28 
DPT$W_INITT AB • A-27 
DPT$W_MAXUNITS • A-28 
DPT$ W_REINITT AB • A-27 
DPT$ W_SIZE • A-26 
DPT$W_UCBSIZE • A-26 
DPT$W_UNLOAD* A-27 
DPT$W_VECTOR • A-28 
DPT$W_VERSION • A-28 
DPT_STORE macro *7-3, 7-5, 13-1, 
13-3 B-10 

DPTAB macro* 7-2, 7-3, B-5 
DEFUNITS argument* 14-20 
DELIVER argument* 14-20 
DR32 driver *G-1 
Driver 

compiling *14-1 


Driver (cont'd.) 

components of a* 1-3, 5-28 

dispatch table* 13-2 

displaying the location of* 14-12 

DR32 • G-1 

functions of* 1-14 

initialization • 14-7 

internal queues *8-24 

linking *14-1 

loading* 14-1, 14-2 

MASSBUS* 13-3, G-1 

special considerations*G-15 
preprocessing • 2-5 
prologue table 

initialization • 13-2 
Q-bus example *E-1 
reloading a *7-4 
replacing* 14-9 
source file* 14-1 
specifying the name of* 7-5 
suspending the *9-3, 9-8 
tables* 1-7, 6-2, 7-1 
creating* 7-1 
template *6-1 
transfer address* 14-2 
unloading a • 7-4 
Driver-dispatch table 
See DDT 

Driver-loader's flags *7-4 
Driver-loading procedure* 1-22, 6-1, 
7-2, 7-4, 10-4, 10-6, 14-9 
fields in the I/O database reinitialized 
by* 14-9 

Driver-prologue table 
See DPT 

Driver-unloading procedure • 7-4 
DSBINT macro*3-18, 9-7, 9-8, 12-9, 
B-11 


E 


ECC error correction • 7-4 

EMB$I_DV_REGSAV • 13-10 

ENBINT macro *3-18, B-12 
End-of-driver label *6-1, 7-4 
$EQULST macro* B-13 
ERL$DEVICERR • 13-9, C-8 
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ERL$DEVICTMO • 13-9, C-9 
ERL$RELE ASEMB • 12-5 

ERI_DEVICTMO • 12-7 

Error-handling routine • 9-7 
Error-log buffer* 7-9 
size* 13-10 
Error-logging bit* 12-4 
Error-logging routine* 1-3, 1-17, 13-9 
Error-message buffer* 12-4 
releasing* 12-5 
Error-recovery routine • 1 -3 
Error-status bit* 13-1 
Event flag *5-22, 8-19 
Exception vector *3-6 
EXE$ABORTIO • 8-7, 8-18, C-10 
EXE$ ALLCBUF • 8-8 
EXE$ ALLOCBUF • C-11 
EXE$ ALLOCIRP • C-12 
EXE$ ALONONP AGED • C-13 
EXESALOPHYCNTG• C-14 
EXESALOPHYSNTG routine *D-7 
EXESALTQUEPKT • 7-9, 8-6, 8-24, 
C-15 

EXESBUFFERQUOTA • 8-8 
EXESBUFFRQUOT A • C-16 
EXESBUFQUOPRC • C-17 
EXESCANCEL* 13-5 
EXESDEANONPAGED • C-18 
EXESFINISHIO• 8-7, 8-14, 8-19, C-19 
EXESFINISHIOC • 8-7, 8-19, C-20 
EXESFORK • C-21 
EXESINSERTIRP • 8-23, C-22 
EXESINSIOQ • 8-22, 9-1, C-23 
EXESINSTIMQ • C-24 
EXESIOFORK* 10-10, 12-2, C-25 
EXESLCLDSKV ALID • C-26 
EXESMODIFY • C-28 
EXESMODIFYLOCK • C-30 
EXESMODIFYLOCKR • C-32 
EXESONEPARM *8-11, C-34 
EXESQIODRVPKT • 7-9, 8-6, 8-21, 
9-1, C-35 

EXESQIORETURN • 8-25, C-36 
EXE$READ*8-7, 8-12, C-37 
EXESREADCHK • 8-8, C-38 
EXESREADCHKR *8-12, C-39 
EXE$READLOCK *8-12, C-40 
EXESREADLOCKR *8-12, C-41 
EXESSENSEMODE *8-14, C-42 
EXESSETCHAR* 8-14, C-44 


EXESSETMODE *8-14, 8-15, C-46 
EXESSNDEVMSG • 12-9, C-48 
EXESWRITE • 8-7, 8-16, C-50 
EXE$WRITECHK*8-8, C-51 
EXESWRITECHKR *8-16, C-52 
EXESWRITELOCK *8-16, C-53 
EXESWRITELOCKR*8-16, C-55 
EXESWRTM AILBOX • C-56 
EXESZEROPARM *8-17, C-57 


F 


Fatal bugcheck*3-9 
FDT (function-decision table)* 1-3, 7-1, 
13-2 

address of • 7-9 
entry • 5-12, 7-10, 7-11 
use of • 5-13 
FDT processing 
terminating* 7-11 

FDT routine* 1-15, 2-5, 7-11,8-1, 
8-24, 1-1 

access to device registers*8-21 
allocating a system buffer *8-8 
calling sequence *8-4 
checking data transfer's byte-count* 
9-6 

context of execution • 5-14, 8-1 
conventions*8-2, 8-3 
device-independent *8-11 
exiting from • 8-4 
exiting mechanisms • 8-4 
for buffered I/O *8-8 
for direct I/O*8-7 
postprocessing • 8-25 
register use by • 8-3 
registers preset for *8-2 
terminating execution • 8-18 
terminating execution of *8-4 
use of registers *6-2, 8-18 
Floating CSR 

address calculation* 14-22 
Floating vector 

address calculation* 14-21 
Fork block *3-19, 8-24, 9-4 
Fork context* 1-5, 3-21 
Fork IPL* 1-5, 1-11, 3-11, 4-1 
FORK macro*B-14 
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Fork process* 1-4, 1-12, 3-3, 3-19, 
9-1, 9-8, 10-2 
activation • 5-20 
context *5-16 
creation* 5-14, 11-8, 11-9 

for interrupt processing*5-19 
execution* 5-16 
execution context *9-2 
suspension* 5-17 

synchronizing with other activities* 
8-22 

Fork processing *3-11 
Fork queue* 1-12, 5-20 
Fork-process dispatching • 3-20 
FUNCTAB macro • 7-11, 7-15, B-15 
Function-decision table 
See FDT 


H 


Hardware interrupt*9-8, 10-10 
generating* 11-1 


I 


I/O completion • 5-20 
I/O database* 1-7, 13-2, 13-3, A-1, 
G-1, G-16 

creation* 14-7, 14-13, G-8 
initializing • 7-2 
modifying • 8-22 
read-only fields* A-1 
referring to fields in *6-2 
I/O operation 
retrying* 12-7 

I/O postprocessing • 5-1, 5-20 
I/O preprocessing 

device dependent • 5-1 
device independent*5-1 
I/O processing 
phase of • 5-1 
I/O request 

aborting* 12-8 
completing *12-1, 12-3 
1/0-completion processing • 2-9, 3-11 
l/O-database initialization* 1-23 
l/O-function code *5-11, 7-10, 9-5 
device-specific* 7-11 
for accessing a file *7-13 


l/O-function code (cont'd.) 

for acknowledging a disk pack* 
7-12 

for clearing a drive *7-12 
for creating a file *7-13 
for deaccessing a file *7-13 
for deleting a file *7-13 
for diagnosis* 7-12 
for erasing a tape *7-12 
for logical 1/0*7-13 
for miscellaneous ACP control *7-13 
for modifying a file *7-13 
for mounting a volume *7-13 
for no operation* 7-12 
for offsetting read/write heads* 
7-12 

for physical 1/0*7-12 
for reading a header and data *7-12 
for reading a physical block *7-12 
for reading a terminal with a prompt 
•7-14 

for reading a virtual block *7-14 
for reading preset *7-12 
for reading track data *7-12 
for recalibrating a drive *7-12 
for releasing a port *7-12 
for returning heads to center *7-12 
for rewinding a tape *7-13 
for rewinding a tape and setting it 
off line *7-13 

for searching for a sector *7-12 
for seeking a cylinder* 7-12 
for sensing device charisterics • 7-12 
for sensing the device mode *7-13 
for setting device available • 7-12 
for setting device characteristics* 
7-12 

for setting the device mode *7-13 
for skipping files *7-13 
for skipping records *7-13 
for spacing files *7-12 
for spacing records *7-12 
for starting a spindle *7-13 
for unloading a drive *7-13 
for virtual I/O* 7-13 
for write-checking a header and 
data *7-13 

for write-checking data *7-13 
for writing a header and data *7-13 
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l/O-function code (cont'd.) 

for writing a physical block*7-13 
for writing a tape mark *7-13 
for writing a virtual block *7-14 
for writing logical blocks *7-13 
for writing the end-of-file mark* 
7-13 

for writing track data *7-13 
list *7-12 

l/O-function modifier *5-11 
1/0-postprocessing queue* 12-4 # 13-6 
l/O-request packet 
See IRP 

1/0-status block 
See ISB 

IDB (Interrupt-dispatch block)* 1-9, 
3-6, 5-4, 5-7, 9-4 
size* 7-5 

IDB$B_COMBO_CSR • A-31 
IDB$B_COMBO_VEC • A-31 
IDB$B_TT_EN ABLE • A-31 
IDB$B_TYPE • A-30 
IDB$B_VECTOR • A-30 

IDB$I_ADP • A-31 

IDB$I_CSR • A-30, G-5, G-6 

IDB$l_OWNER • 9-5, 9-10, 11-8, 

13-1, A-30 

IDB$I_UCBLST • A-31 

IDB$W_SIZE • A-30 
IDB$W_UNITS • 14-7, A-30 
IFNORD macro *B-16 
IFNOWRT macro *B-17 
IFRD macro *B-18 
IFWRT macro *B-19 
Indirect-vector UNIBUS adapter* 1-2 
Initialization data *7-3 
Initialization routine* 1-3, 1-14, 13-1 
Instruction 

operand • 6-4 
string-handling • 6-4 
that refers to I/O space *6-5 
Interconnection device 
generic name* 14-10 
Interrupt 

direct-vector *3-6, 11-1, 11-2 
disabling *3-18 
dismissing *3-1, 12-1 
enabling *3-18 
expected • 3-7 


Interrupt (cont'd.) 

hardware • 9-8, 10-10 
generating a* 11-1 
nondirect-vector*3-5, 11-1, 11-2 
processing* 1-12, 5-18 
by VAX/VMS • 3-5 
requesting a software*3-19 
servicing a* 11-5 
UNIBUS-device 
dispatching *3-5 
unsolicited 

example of an • 11-8 
servicing a* 11-7 
waiting for an *9-8, 10-2 
Interrupt context* 1-5, 3-3, 3-4, 3-6, 
9-10 

Interrupt dispatcher* 1-2, 3-6, 10-10 
Interrupt priority level 
See IPL 

Interrupt stack *3-6 
Interrupt unexpected • 3-6 
Interrupt-dispatch block 
See IDB 

Interrupt-dispatching code *3-6 
Interrupt-dispatching field* 11-2 
Interrupt-enable bit *9-6 
Interrupt-expected bit* 12-8 
Interrupt-servicing routine* 1-3, 1-16, 
2-8, 3-1, 5-1, 7-3, 9-10, 10-10, 
12-8, 1-6 

context of execution* 11-4 
functions*5-18, 9-11, 11-1 
writing* 11-1 
IO$_ACCESS *7-13 
IO$_ACPCONTROL *7-13 
IO$_AVAILABLE *7-12 
IO$_CRE ATE *7-13 
IO$_DE ACCESS *7-13 
IO$_DELETE *7-13 
IO$_DI AGNOSE *7-12 
IO$_DRVCLR *7-12 
IOS—ER ASET APE *7-12 
IO$_MODIFY *7-13 
IO$_MOUNT *7-13 
IOS—NOP* 7-12 
IO$_OFFSET *7-12 
IO$_PACKACK *7-12 
IO$_RE ADBLK *7-13 


Index—8 



Index 


IO$_RE ADHE AD *7-12 
IO$_RE ADPBLK *7-12 
IO$_RE ADPRESET • 7-12 
IO$_RE ADPROMPT *7-14 
IO$_RE ADTR ACKD • 7-12 
IO$_RE ADVBLK *7-14 
IO$_REC AL *7-12 
IO$_RELE ASE *7-12 
IO$_RETCENTER* 7-12 
IO$_RE WIND *7-13 
IO$_RE WINDOFF *7-13 
IOS—SE ARCH *7-12 
IO$_SEEK*7-12 
IO$_SENSECH AR *7-12 
IO$_SENSEMODE *7-13 
IO$_SETCHAR* 7-12 
IO$_SETMODE *7-13 
IOS—SKIPFILE *7-13 
IO$_SKIPRECORD *7-13 
IO$_SPACEFILE *7-12 
IO$_SPACERECORD *7-12 
IO$_ST ARTSPNDL *7-13 
IO$_UNLO AD *7-13 
IO$_WRITECHECK *7-13 
IO$_WRITECHECKH *7-13 
IO$_WRITEHEAD* 7-13 
IO$_WRITELBLK *7-13 
IO$_WRITEM ARK • 7-13 
IOS—WRITEOF *7-13 
IO$_WRITEPBLK *7-13 
IO$_WRITETR ACKD *7-13 
IO$_WRITEVBLK *7-14 
IOC$ ALOUB AM AP • C-58 
IOC$ ALOUBAMAPN • 10-6 
IOCS APPLYECC • C-60 
IOCSCancel-1/O • C-61 
IOC$CANCELIO routine* 13-8 
IOC$DI AGBUFILL • C-62 
IOC$INITIATE • 8-22, 9-1, C-64 
IOC$INSIOQ • 9-3 
IOC$IOPOST • C-66 
IOC$LOADMBAM AP • G-5 
IOC$LO ADUB AM AP • 10-7, C-68 
IOC$LOADUBAMAPA • 10-8 
IOC$MNTVER • 7-9 
IOC$MOVFRUSER • C-70 
IOCSMOVFRUSER routine *D-8 
IOC$MOVFRUSER2 • C-71 
IOC$MOVT OUSER • C-72 
IOCSMOVTOUSER routine *D-8 


IOC$MOVTOUSER2 • C-73 
IOCSPURGD AT AP • C-74 
IOC$PURGDATAP routine • D-8 
IOC$RELCHAN* 12-3, C-76 
IOC$RELDATAP* 10-12, C-77 
I0CSRELMAPREG • 10-13, C-79 
IOC$RELSCH AN • C-81 
IOC$REQCOM • 9-1, 12-4, C-82 
IOC$REQDATAP • 10-2, C-84 
IOC$REQDAT APNW • 10-3 
IOC$REQMAPREG* 10-5, C-86 
IOCSREQPCHANH • C-88 
IOC$REQPCHANL • 9-3, C-90 
IOC$REQSCHANH • C-91 
IOC$REQSCH ANL • C-92 
IOC$RETURN *7-10, 13-7, C-93 
IOCSVERIFYCHAN • C-94 
IOCSWFIKPCH • 9-9, C-95 
IOCSWFIRLCH • C-97 
$IODEF macro *7-11 
IOFORK macro *3-4, 3-20, 10-10, 

11-6, 12-1, B-20 
functions of • 5-19 

IPL (interrupt priority level)* 1-11, 3-1 
changing *3-14, 3-16 
device • 3-6 

lowering *3-3, 3-4, 3-11, 9-10 
raising • 3-4 
setting *3-18 
IPL 0*8-23 
IPL 11*3-12 

See also IPL$_MAILBOX 
IPL 2*3-15 
IPL 3*3-12 

See also IPL$_SCHED 
IPL 31*3-12 

See also IPL$_POWER 
IPL 4*3-11 

See also IPL$_IOPOST 
IPL 5*3-12 

See also IPL$_XDELTA 
IPL 6*3-12 

See also IPL$_QUEUEAST 
IPL 8*3-12 

See also IPL$_SYNCH and IPL$_ 
TIMER 
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IPL$_ASTDEL* 1-11, 3-2, 3-9, 3-15, 
5-10, 8-1, 8-20, 8-23 
IPL$_IOPOST* 1-11, 3-2, 3-11, 5-22, 
8-19 

IPL$_M AILBOX • 3-12, 11-10 
IPL$_POWER *3-12, 9-7, 9-8, 12-9, 
13-2, 14-7 

IPL$_QUEUEAST*3-2, 3-12 
IPL$_SCHED • 3-2, 3-11 
IPL$_SYNCH* 1-11, 3-2, 3-12 
IPL$_TIMER • 3-2, 3-12, 12-6, 12-8 
IPL$_XDELTA • 3-2, 3-12 
IPL$IOPOST • 8-20 
IRP (l/O-request packet)* 1-7, 1-10, 
2-4, 5-10, 6-2, 8-23 
allocation of • 5-10 
contents of • 5-10 
queuing the *2-6 
IRP$B_CARCON *8-12, 8-16 
IRP$B_EFN • A-34 
IRP$B_PRI • A-34 
IRP$B_RMOD *8-19, A-33 
IRP$B_TYPE • A-33 

IRP$I_ABCNT • A-38 

1RP$I_ARB • A-39 

IRP$I_AST • A-33 

IRP$l_ASTPRM • A-33 

IRP$I_BCNT • A-37 

IRP$I_DIAGBUF • 8-22, A-38 

IRP$I_EXTEND • A-39 

IRP$l_IOQBL* A-33 
IRP$L_IOQFL* A-33 

IRP$I_IOSB *8-19, A-35 

IRP$I_IOST1 • A-37 

IRP$l_IOST2 • A-37 

IRP$I_KEYDESC • A-39 

IRP$L_MEDIA *8-11, 8-15, 8-20, 

12-4, 13-6 
IRP$l_OBCNT* A-38 

IRP$I_PID* 13-8, A-33 

IRP$I_SEGVBN • A-38 

IRP$I_SEQNUM • A-38 

IRP$I_SVAPTE • 8-8, 8-10, 8-13, 

8-22, 9-2, A-36 

IRP$I_UCB • A-34 

IRP$I_WIND* A-34 
IRP$V_BUFIO* A-36 
IRP$V_CHAINED • A-36 
IRP$ V_COMPLX • A-36 


IRP$V_DIAGBUF • 8-22, A-36 
IRP$V_EXTEND • A-36 
IRP$V_FILACP • A-36 
IRP$V_FUNC • 8-8, 8-10, 8-12, 13-6, 
A-36 

IRP$V_KEY • A-36 
IRP$V_MBXIO* A-36 
IRP$V_MVIRP • A-36 
IRP$V_PAGIO • A-36 
IRP$V_PHYSIO* A-36 
IRP$V_SWAPIO • A-36 
IRP$V_TERMIO • A-36 
IRP$V_VIRTUAL* A-36 
IRP$W_BCNT • 8-8, 8-16, 8-22, 9-2 
IRP$W_BOFF • 8-8, 8-10, 8-22, 9-2, 
A-37 

IRP$W_CHAN* 13-8, A-35 
IRP$W_FUNC *8-16, 9-5, A-34 
IRP$W_SIZE • A-33 
IRP$W_STS • 8-8, 8-10, 8-12, 13-6, 
A-35 

IRPE$B_TYPE • A-41 

IRPE$I_BCNT 1 • A-41 

IRPE$L_BCNT2 • A-41 

IRPE$I_EXTEND • A-41 

IRPE$I_SVAPTE 1 • A-41 

IRPE$I_SV APTE2 • A-41 

IRPE$V_EXTEND • A-41 

IRPE$W_BOFF1 • A-41 

IRPE$W_BOFF2 • A-41 

IRPE$ W_SIZE • A-41 

IRPE$W_STS* A-41 

ISB (l/O-status block) *5-9, 12-4 

ISR 

See interrupt-servicing routine 


J 


JIB (job-information block)*8-9 

JIB$I_BYTCNT *8-9, 8-10 

Job-attached bit* 11-9 
Job-information block 
See JIB 


K 


Kernel-mode AST*3-11, 5-22, 8-10 
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L 


LINK command* 14-1 
Loading drivers* 1-22 
LOADMBA macro *B-21 
LOADUBA macro *B-22 
Logical I/O *2-4 

Longword-access-enable bit *4-11 
Longword-enable bit *4-4 
LWAE bit *4-4 


M 


Machine independence* 1-2 
MACRO command* 14-1 
Macro library* 14-1 
Mailbox 

for operator* 12-9 
Mailbox driver* 14-5 
Map-lock bit* 10-6 

M AP$I_ERB • G-6 

M AP$I_MAP • G-6 

Mapping register* 10-1 
allocating* 10-1, 10-5 
allocating permanently* 10-6 
calculating the number needed* 
10-5 

deallocating* 10-1 
loading* 10-1, 10-2, 10-7 
releasing • 10-2, 10-13 
requesting • 10-2 

Mapping-register-valid bit *4-3, 10-7 
Mapping-register-wait queue* 10-5, 
10-13 
MASSBUS 

attention-summary register*G-12 
device 

register* G-6 
driver* 7-9, G-1 

special considerations • G-15 
MASSBUS adapter* 1-2 
address space *G-5 
attention-summary register *G-7 
generic name* 14-10 
loading registers*G-4 
mapping registers • G-6 
number *G-2 


MASSBUS adapter (cont'd.) 

obtaining ownership of*G-8 
operations* G-11 
registers* G-2 

MBA 

See MASSBUS adapter 

MBA$I_AS • G-7 

$MBADEF macro *G-5 
Memory allocation • 3-9 
Memory controller 

generic name* 14-10 
Message 

sending the operator a* 12-9 
MicroVAX I Q-bus* 1-3, D-1 
MMG$IOLOCK *8-13 
Mount-verification routine *7-9 
MSG$_DEVOFFLIN • 12-9 
Multiunit controller • 5-6 


N 


Nexus* 14-5 
Non-DMA transfer* 1-20 


o 


Online bit* 13-4 
OPCOM 

message code* 12-9 
process* 12-9 
Operand 

double *6-4 
field • 6-4 
floating • 6-4 
quadword • 6-4 
queue • 6-4 

ORB$B_FLAGS • A-43 
ORB$B_TYPE• A-42 

ORBS I_ACI_MUTEX • A-42 

ORB$l_ACLBL* A-43 

ORB$l_ACLFL • A-43 

ORB$l_OWNER • A-42 

ORB$V_ACI_QUEUE • A-43 

ORBS V_NOACL • A-43 
ORBS V_PROT_ 16 • A-43 
ORB$W_PROT* A-43 
ORB$W_SIZE* A-42 
Out-of-band-AST request 
canceling* 13-7 
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p 


Page fault *3-9, 8-17 

during FDT execution • 8-13 
Page-table entry *8-13 

PCB$I_MB • 8-9 

PCB$I_PID • 13-8 

Pending-I/O queue *8-21, 8-23, 8-24, 
9-1, 13-6 

Physical address* 1-2 
Plus-sign character • 7-10 
Position-independent code *6-1 
Post-transfer processing* 12-1 
Postprocessing *3-11 
Postprocessing queue *3-11 
Power bit* 12-6 
Power failure*9-7 
checking for*9-7 
Power-fail IPL*3-12 
Powerfail-recovery procedure* 13-3 
Prefetch *4-9, 4-10 
Preprocessing* 1-3 
terminating *5-14 
Preprocessing routines* 5-13 
Process context* 1-5, 2-6 
Process I/O channel *5-2 
Process quota *3-11, 5-9, 5-22, 7-14, 
8-19 

Program section $$$115—DRIVER* 
14-1 

Programmed 1/0*7-14 
.PSECT directive* 14-1 
PURDPR macro* 10-11, B-23 


Q 


Q-bus 

comparison with UNIBUS *D-2 
Q22 bus* 1-3, D-1 
$010*2-3 
QIO 

arguments *2-3, 8-12 
processing* 7-12 
system service *2-3 
Queue 

channel-wait • 9-3 
data-path-wait • 10-3, 10-12 
fork-wait* 5-20 


Queue (cont'd.) 

1/0-postprocessing* 12-4 
mapping-register-wait* 10-5, 10-13 
pending-1/0 • 8-23, 9-1, 13-6 
postprocessing *3-11 
resource-wait* 1-13, 3-23 
Queue-I/O-Request system service* 
5-1 

Queuing the IRP*2-6 


R 


R4* 5-18 
R5 • 5-18 

Reentrant code *6-1 
Register 

of devices connected to the SBI • 
6-4 

of the MASSBUS • 6-4 
of the UNIBUS adapter *6-4 
using *6-2 

Register-dumping routine *7-9, 13-9, 
13-10, 1-12 
REI instruction *8-23 
Reinitialization 

of controllers* 7-4 
Reinitialization data *7-3 
RELCHAN macro* 12-3, B-24 
RELDPR macro* 10-12, B-25 
RELMPR macro* 10-13, B-26 
RELSCHAN macro *B-27 
REQCOM macro* 12-4, 12-7, B-28 
REQDPR macro* 10-2, B-29 
REQMPR macro* 10-5, B-30 
REQPCHAN macro *9-3, B-31, G-8 
PRI=HIGH argument *9-3 
REQSCHAN macro *B-32, G-8 
Resource allocation* 1-13, 1-16 
Resource deallocation • 5-22, 10-11 
Resource-wait queue* 1-13, 3-23 
Resource-wait-queue entry *3-23 
RSB instruction • 8-6 
Rules 

for position-independent code *6-2 
for reentrant code *6-2 


s 


SAVIPL macro «B-33 
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SCB (System-control block) *3-6 
SCB-base register *3-6 
SCBB 

See SCB-base register 
SETIPL macro*3-18, 12-9, B-34 
Setting device characteristics*8-14 
Setting device mode *8-14 
Shared controller*3-24 
Shared resources* 1-13 
SOFTINT macro *3-19, B-35 
Software devices* 14-5 
Software-interrupt-expected bit* 11-6, 
11-8 

Solicited interrupt 
servicing *11-5 
SPARE$L* A-39 
SS$_ABORT • 12-8 
SS$_ACCVIO *8-13 
SS$_CANCEL* 13-6 
SS$_INSFWSL *8-13 
SS$_NORM AL *8-14 
SS$_SETCHAR *8-15 
Stack *3-24 
using *6-2 

Start-I/O routine* 1-3, 1-15, 5-1, 
5-16, 7-9, 9-1, 9-5, 9-6, 10-2, 
G-17, 1-3 

alternate*7-9, 8-24 
context • 8-23 
entry point *2-6, 8-22 
execution context *9-2 
functions of • 5-17 
transferring control to • 8-23 
writing a *9-1 
Status code 

saving the* 12-4 
Suspending the driver *9-8 
Swapping overhead • 7-14 
Synchronization* 1-4, 1-11,3-1 
of controller use *3-24 

SYSSGI_OPRMBX • 12-9 

SYS$LIBRARY:STARLET.MLB* 7-1 1 
SYS$SYSTEM:LIB.MLB • 14-1 
SYSGEN (System Generation Utility)* 
14-2 

AUTOCONFIGURE command* 13-2 
command 

RELOAD* 13-3 

CONNECT command* 13-2, 14-4 


SYSGEN (corn'd.) 

CONNECT command (cont'd.) 
/ADAPTER qualifier* 14-5 
/ADPUNIT qualifier* 14-6 
/CSR qualifier* 14-5 
/CSR_OFFSET qualifier* 14-5 
/DRIVERNAME qualifier* 14-6 
/MAXUNITS qualifier *7-5, 14-7 
/NUMVEC qualifier* 11-4, 14-6 
risks of using the* 14-8 
/VECTOR qualifier* 14-6 
/VECTOR_OFFSET qualifier* 
14-6 

device table • 14-15 
LOAD command* 13-2, 14-3 
RELOAD command* 14-8 
restriction* 14-10 
SHOW command 

/CONFIGURATION qualifier* 

14-1 1 

/DEVICE qualifier* 14-12 
SHOW command/ADAPTER 
qualifier* 14-10 
System buffer 
address* 8-8 
format of • 8-9 
size* 8-8 

System page-table entry *7-4 
System-control block 
See SCB *3-6 
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Temporary storage *6-2 
Terminal 1/0*7-14 
TIMEDWAIT macro *B-37 
Timeout • 9-8, 9-11 
handler 

execution context* 12-6 
waiting for a • 9-8 
Timeout routine 

calculating the address of *9-10 
Timeout-handling routine • 9-11, 12-1, 
1-10 

Timer routine 

VAX/VMS* 12-5 
TIMEWAIT macro *B-36 
Transfer vector *7-5 
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UCB (unit-control block)* 1-9, 5-4, 6-2, 
8-23 

address *5-18 
cloned *7-10 

creation* 13-2, 14-7, 14-20 
error-log extension* 13-10 
extending • 7-4 
size* 7-4 

UCB$B_AM0D • A-53 
UCB$B_CEX• A-58 
UCB$B_DEVCHAR2 • A-49 
UCB$B_DEVCLASS *8-15, A-27, 

A-50 

UCB$B_DEVTVPE *8-15, A-27, A-51 
UCB$B_DIPL*3-12, 7-3, 12-5, A-27, 
A-53 

UCB$B_DX_SCTCNT • A-61 
UCB$B_ERCNT• 12-4 
UCB$B_ERTCNT• A-56 
UCB$B_ERTM AX • A-56 
UCB$B_FEX* A-58 
UCB$B_FIPL*3-11, 7-3, 12-2, A-27, 
A-44 

UCB$B_OFFNDX • A-61 
UCB$B_OFFRT C• A-61 
UCB$B_SLAVE* A-58, G-15 
UCB$B_SPR• A-58 
UCB$B_TYPE• A-44 

UCB$I_AMB • A-53 

UCB$I_BCR • A-60 

UCB$I_CRB • A-46 

UCB$I_DCCB • A-59 

UCBSl_DDB • A-47 

UCB$I_DDT • A-57 

UCB$1_DEVCHAR • 7-3, 13-10, A-27, 

A-47 

UCB$I_DEVDEPEND *8-14, 8-15, 

A-27, A-51 

UCB$I_DEVDEPND2 • A-52 

UCB$I_DPC • A-58 

UCBSl_DUETIM *9-10, 12-6, A-55 

UCBSl_DX_BFPNT • A-61 

UCBSl_DX_BUF • A-61 

UCBSl_DX_RXDB • A-61 

UCBSl_EMB* 12-4, A-58 

UCB$I_FPC* 12-2, 12-6, A-46 


UCB$I_FQBL* A-44 

UCBSL_FQFL* A-44 

UCB$I_FR3* 11-6, 12-2, 12-5, A-46 
UCB$L_FR4* 11-6, 12-2, 12-5, A-46 
UCB$l_IOQBL • A-52 

UCBSl_I0QFL • 8-24, A-52 

UCBSl_IRP • 8-22, 12-4, A-52 

UCBSl_LINK • A-47 

UCBSl_LOCKID • A-46 

UCBSl_MAXBLOCK • A-59 

UCBSl_MEDIA • A-60 

UCBSl_OPCNT • 8-20, A-55 

UCBSl_ORB • A-46 

UCBSl_PDT • A-57 

UCBSl_PID • A-47 

UCBSl_STS • 8-22, 9-7, 9-10, 11-6, 

11- 8, 11-10, 12-2, 12-4, 12-5, 
13-8, A-53 

UCB$I_SVAPTE • 8-22, 9-2, 10-7, 
A-56 

UCB$L_SVPN • 7-4, A-55 

UCBSl_VCB • A-47 

UCB$V_BSY • 2-6, 8-22, 8-24, 12-5, 
13-8, A-53 

UCB$V_C ANCEL • 8-22, 12-9, 13-8, 
A-53 

UCB$V_DE ADMO • A-53 
UCB$V_DELETEUCB • A-54 
UCB$V_DELMBX • A-55 
UCB$V_DI AGBUF • A-58 
UCB$V_ECC• A-58 
UCB$V_ERLOGIP • 12-4, A-53 
UCB$ V_INT *9-10, 11-6, 11-8, 12-5, 

12- 8, A-53 

UCB$V_INTTYPE • A-53 
UCB$V_J0B • 11-9, A-55 

UCB$V_LCI_VALID • A-54 

UCBS V_MNTVERIP • A-54 
UCBS V_MNTVERPND • A-54 
UCB$V_MOUNTING • A-53 
UCBS V_NOCNVRT • A-58 
UCB$V_ONLINE • 13-1, 13-4, A-53 
UCB$V_POWER • 9-7, 12-6, A-53 
UCB$V_PRMMBX • A-55 
UCB$V_SHMMBS • A-55 
UCBS V_SUPMVMSG • A-54 
UCB$V_TEMPLATE • A-54 
UCB$V_TIM *9-10, 12-2, 12-5, A-53 
UCB$V_TIMOUT • 8-22, 12-5, A-53 
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UCB$V_UNLOAD • A-54 
UCB$V_VALID • 11-10, A-54 
UCB$V_WRONGVOL* A-54 
UCB$W_BCNT• 8-22, 9-2, 9-6, 10-5, 
10-7, A-56, G-5 
UCB$ W—BCR • A-61 
UCB$W_BOFF• 8-22, 9-2, 9-6, 10-5, 
10-7, 10-8, A-56, G-4 
UCB$W_BUFQUO • A-46 
UCB$ W_CH ARGE • A-52 
UCB$ W_DEFBUFSIZ • 8-15 
UCB$W_DEVBUFSIZ• A-27, A-51 
UCB$W_DEVSTS* 1 1-9, 12-4, A-54 
UCB$W_DIRSEQ • A-59 
UCB$W_EC1 • A-60 
UCB$ W_EC2 • A-61 
UCB$W_ERRCNT • A-57 
UCB$W_FUNC • A-58 
UCB$ W_OFFSET • A-61 
UCB$W_ONLCNT • A-59 
UCB$W_QLEN • A-55 
UCB$W_REFC • 1 1-9, A-52 
UCB$W_REFCNT • 11-9 
UCB$W_SIZE • A-44 
UCB$W_SRCADDR • A-46 
UCB$W_UNIT • A-52 

UCBTV_TEMPl_BSY • A-55 

UNIBUS 

comparison with Q-bus*D-2 
I/O space 

accessing • 6-5 
mapping register *4-3 
on VAX-11/725*4-14 
on VAX-11/730*4-14 
on VAX-11/750*4-13 
on VAX-11/780*4-12 
on VAX-1 1/782*4-12 
on VAX-1 1/785*4-12 
reading operation *4-8, 4-11 
registers *4-2 

synchronization of access to *4-1 
writing function • 4-12 
UNIBUS adapter* 1-2, 4-1 
data-path register* 10-1 
direct-vector* 1-2 
generic name* 14-10 
indirect-vector* 1-2 
mapping register* 10-1 
registers* 10-1 

UNIBUS address *4-2, 9-6, H-1 


UNIBUS address (cont'd.) 
calculation* 10-2 
mapping • 4-2 
space *4-2 
translation of *4-3 
UNIBUS device 

byte-addressable* 10-8 
Unit number* 7-5 
Unit-busy bit* 12-5 
Unit-control block 
See UCB 

Unit-delivery routine* 14-20, 1-18 
execution context* 14-20 
specifying a*7-5 

Unit-initialization routine*7-9, 9-5, 
10-4, 13-3, G-15, 1-16 
address of • 7-3 
execution context* 13-4 
input* 13-5 
MASSBUS* 13-3 
Unit-status register* 13-4 
Unsolicited interrupt 
example* 11-8 
servicing *11-7 

Unsolicited-interrupt routine* 7-9 
Unsolicited-interrupt-handling routine • 
1-9 

User buffer* 1-15 
User-mode AST • 5-23 
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VAX-11/750 
data paths* 10-4 
VAX-11/780* 10-4 
VAX/VMS preprocessing • 2-3 
VAX/VMS timer routine* 12-5 
VEC$B_DATAPATH* 10-3, 10-7, 

A-18 

VEC$B_NUMREG* A-17 

VEC$I_ADP • A-18 

VECSl_IDB • A-16 

VEC$I_INITIAL • A-16, A-27 

VEC$1_UNITINIT • A-19, A-27 

VEC$Q_DISPATCH • A-16 
VECSV_LWAE *4-1 1, 10-7, A-18 
VEC$V_MAPLOCK • 10-6, A-17 
VECS V_M APREG • A-17 
VEC$V_PATHLOCK • 10-3, 10-4, A-18 
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VEC$ W_M APREG • A-1 7 
Vector address*3-6 
Vector-jump table *3-5 
$VIELD macro *B-39 
_VIELD macro *B-40 
Virtual I/O *2-4 
Volume-valid bit* 11-10 
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Wait-for-interrupt macro* 1-16, 12-1 
Wait-for-interrupt routine *2-7 
Waiting for an interrupt* 10-2 
WFIKPCH macro *9-8, 13-9, B-41 
expansion • 9-9 
WFIRLCH macro *9-8, B-42 
Working-set limit 
insufficient* 8-13 
WRIRLCH macro *9-8 
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